Field

A semantic wrapper that coordinates a form control with its label, description, validation, and error message.

Use Field whenever a control needs supporting text or validation. The control owns its editable UI; Field owns the surrounding form relationship.

Username

Choose a unique username.

Labeled field

Installation

$npx shadcn@latest add @patchui/field

The copied source is available in the registry JSON. The canonical implementation lives in packages/react/src/components/field.tsx.

Usage

<Field name="username">
  <FieldLabel>Username</FieldLabel>
  <Input placeholder="ada_lovelace" />
  <FieldDescription>Choose a unique username.</FieldDescription>
</Field>

FieldLabel and FieldDescription coordinate accessible labeling and description through the underlying Base UI Field primitive.

Composition

Field
├── FieldLabel
├── control, such as Input or FieldControl
├── FieldDescription
├── FieldError
└── FieldValidity (optional)

Use FieldItem when a Field groups multiple checkbox or radio rows.

Examples

Invalid field

Set Field invalid when application state owns validation, and mirror that state on the control with aria-invalid.

Enter the address used for notifications.

Enter a complete email address.

Invalid field

API reference

Prop	Type	Default	Description
name	string	-	Identifies the field in form values and validation.
invalid	boolean	false	Marks externally controlled field state as invalid.
disabled	boolean	false	Disables the field and its registered control.
validate	(value, formValues) => string \| string[] \| null	-	Returns custom synchronous or asynchronous validation errors.
validationMode	"onSubmit" \| "onBlur" \| "onChange"	"onSubmit"	Overrides when the surrounding Form validates this field.
validationDebounceTime	number	0	Debounces on-change custom validation in milliseconds.

FieldLabel supports required and optional visual markers. The required marker does not enforce validation, so the underlying control still needs its native required attribute. FieldError displays the current validation message, or custom content supplied through match or children.

Use FieldControl for the unstyled Base UI control, and FieldValidity when custom UI needs the complete validity state. These escape hatches expose their underlying Base UI contracts directly.

Accessibility

Keep one visible FieldLabel for each control. A placeholder is not a label.
FieldDescription and FieldError participate in the control’s accessible description through the Field primitive.
Apply native constraints such as required, type, minLength, and aria-invalid to the control itself.
Required and optional markers are visual annotations and are hidden from assistive technology.
Keep validation messages specific and explain how to correct the value.