baseui-cnField
A form field component that provides labeling, description, and validation for form controls.
Installation
npx baseui-cn add fieldUsage
import {
Field,
FieldLabel,
FieldControl,
FieldDescription,
FieldError,
} from "@/components/ui/field"<Field>
<FieldLabel>Email</FieldLabel>
<FieldControl type="email" placeholder="you@example.com" />
<FieldDescription>We'll never share your email.</FieldDescription>
</Field>Examples
With validation errors
Native HTML validation with required, type, and pattern. Errors appear on form submit.
Pattern validation
Validates username format using the pattern attribute.
Custom validation
Use the validate prop for custom async or sync validation logic. Combined with validationMode="onChange" and validationDebounceTime for real-time feedback.
Disabled
With textarea
Use the render prop on FieldControl to render a <textarea> instead of an <input>.
Form built with Field
Build an entire Base UI form out of Field parts and keep validation, submission state, and help text consistent.
API
Field
Wraps all field parts. Built on Field.Root.
| Prop | Type | Default | Description |
|---|---|---|---|
name | string | — | Identifies the field when a form is submitted |
disabled | boolean | false | Disables the field and all its controls |
invalid | boolean | — | Marks the field as invalid externally |
validate | (value) => string | string[] | null | — | Custom validation function. Return error string(s) or null |
validationMode | "onSubmit" | "onBlur" | "onChange" | "onSubmit" | When to trigger validation |
validationDebounceTime | number | 0 | Debounce for onChange validation (ms) |
FieldLabel
Accessible label auto-associated with the control. Built on Field.Label.
FieldControl
The form control (renders <input> by default). Built on Field.Control. Use the render prop to replace with <textarea> or other elements.
FieldDescription
Helper text below the control. Built on Field.Description.
FieldError
Displays validation errors. Built on Field.Error. Use match to target specific validity states.
| Prop | Type | Description |
|---|---|---|
match | "valueMissing" | "typeMismatch" | "patternMismatch" | "tooLong" | "tooShort" | "rangeOverflow" | "rangeUnderflow" | "stepMismatch" | "badInput" | "customError" | boolean | Which validity state to match |
FieldValidity
Render prop component for custom validity UI. Passes validity state to its child function.
<FieldValidity>
{(state) => <div>{state.validity.valid ? "Valid" : "Invalid"}</div>}
</FieldValidity>API Reference
See the Base UI Field documentation for the full API reference, including all props, data attributes, and CSS classes.