Field

A component that provides labelling and validation for form controls.

Installation


pnpm dlx shadcn@latest add @lumi-ui/field

Anatomy

<Field>
  <FieldLabel />
  <FieldControl />
  <FieldDescription />
  <FieldItem />
  <FieldError />
  <FieldValidity />
</Field>

Warning

Form controls must have an accessible name in order to be recognized by assistive technologies. <FieldLabel> and <FieldDescription> automatically assign the accessible name and description to their associated control.

State and Validation

Required

Error

Validity

{
  "state": {
    "badInput": false,
    "customError": false,
    "patternMismatch": false,
    "rangeOverflow": false,
    "rangeUnderflow": false,
    "stepMismatch": false,
    "tooLong": false,
    "tooShort": false,
    "typeMismatch": false,
    "valid": null,
    "valueMissing": false
  },
  "error": "",
  "errors": [],
  "value": null,
  "initialValue": null,
  "validity": {
    "badInput": false,
    "customError": false,
    "patternMismatch": false,
    "rangeOverflow": false,
    "rangeUnderflow": false,
    "stepMismatch": false,
    "tooLong": false,
    "tooShort": false,
    "typeMismatch": false,
    "valid": null,
    "valueMissing": false
  }
}

Use with other form controls

Select

Autocomplete

Combobox

Note

You can implicitly label <Checkbox>, <Radio> and <Switch> components by enclosing them with <FieldLabel>. See example below.

Checkbox

Fieldset

Radio Group

Integration with Form

See Form Integration for more information.

API Reference

Component	Description
`Field`	Groups all parts of the field. Renders a `<div>` element.
`FieldLabel`	An accessible label that is automatically associated with the field control. Renders a `<label>` element.
`FieldControl`	The form control to label and validate. Renders an `<input>` element. You can omit this part and use any Base UI input component instead. For example, `Input`, `Checkbox`, or `Select`, among others, will work with `Field` out of the box.
`FieldDescription`	A paragraph with additional information about the field. Renders a `<p>` element.
`FieldItem`	Groups individual items in a checkbox group or radio group with a label and description. Renders a `<div>` element.
`FieldError`	An error message displayed if the field control fails validation. Renders a `<div>` element.
`FieldValidity`	Used to display a custom message based on the field’s validity. Requires children to be a function that accepts field validity state as an argument.