# Form Field

Source: https://lumeo.nativ.sh/components/form-field

# Form Field

A composite form field that wraps an input with a label, help text, and error messaging.

## Installation

.NET CLI PackageReference Lumeo CLI

dotnet add package Lumeo

One-time app setup (`AddLumeo()`, CSS & JS) is covered in the [installation guide](docs/introduction).

## Usage

@using Lumeo

<FormField />

Preview Code

Basic

Email

Preview Code

With Help Text

Username

This will be your public display name.

Preview Code

With Error

Password

Password must be at least 8 characters.

Preview Code

Required

Full Name\*

Preview Code

Horizontal Layout

First Name

Last Name

Email

We'll never share your email.

## Async validators

Some validation has to round-trip the server — checking whether a username is taken, whether a coupon code is still valid, whether a domain resolves. `FormField.AsyncValidator` takes a `Func<string?, Task<string?>>` that returns an error message (or `null` for success). It runs alongside the synchronous validator and reports its state through `IsValidating`.

-   **AsyncValidationDebounceMs** (default 300) — wait this long after the last change before firing. Lets fast typists finish before you hit the API.
-   **AsyncValidateOn** — `AsyncValidationTrigger.OnChange` (default) re-runs on every change after the debounce expires; `AsyncValidationTrigger.OnBlur` waits until the field loses focus.
-   **IsValidating** + **OnValidatingChanged** — read this to show a spinner / "Checking…" hint next to the input.
-   **FormContext.IsAnyFieldValidating** — true while any field on the form has a pending async check. Disable the submit button on this so the user can't race a stale validation.

Preview Code

Async validators

Username\*

Try 'taken' to see the async error.

Pair this with an `@bind-IsValidating` or `OnValidatingChanged` handler if you want to render a spinner next to the field while the request is in flight.

## API Reference

### FormField

Property

Type

Default

Description

Label

string?

—

Label text displayed above (vertical) or beside (horizontal) the input.

HelpText

string?

—

Helper text shown below the input. Hidden when an error is present.

Error

string?

—

Error message displayed below the input in destructive color.

Required

bool

false

Shows a red asterisk (\*) next to the label.

Orientation

Lumeo.Orientation

Vertical

Layout direction. Values: Vertical (label above), Horizontal (label beside).

LabelWidth

string?

—

Fixed label width for horizontal orientation (e.g. "120px").

Name

string?

—

Field name passed via cascading FormFieldContext for form integration.