Field

Forms

A wrapper that provides labeling, descriptions, and validation for form controls.

Fields group a label, a control, a description, and an error message into one accessible unit. Validation state is managed automatically, so related UI always stays in sync.

npx shadcn@latest add field

Basic usage

Compose a label, control, and description under a single Field root.

Preview

Live

Full name

Visible on your public profile.

tsx

1<Field name="fullName" className="flex w-64 flex-col items-start gap-1.5">
2  <FieldLabel>Full name</FieldLabel>
3  <FieldControl render={<Input placeholder="Ada Lovelace" />} />
4  <FieldDescription>Visible on your public profile.</FieldDescription>
5</Field>

Validation

Return a message from the validate prop and surface it with FieldError.

Preview

Live

Username

Pick a unique handle.

tsx

1<Field
2  name="username"
3  validationMode="onChange"
4  validate={(value) =>
5    String(value ?? "").length >= 3
6      ? null
7      : "Usernames must be at least 3 characters."
8  }
9  className="flex w-64 flex-col items-start gap-1.5"
10>
11  <FieldLabel>Username</FieldLabel>
12  <FieldControl render={<Input placeholder="e.g. ada" />} />
13  <FieldDescription>Pick a unique handle.</FieldDescription>
14  <FieldError match="customError">
15    Usernames must be at least 3 characters.
16  </FieldError>
17</Field>

API reference

All props of the underlying Base UI primitive are forwarded. The table below documents the Shelf-specific props.

Prop	Type	Description
name	string	Identifies the field when a form is submitted.
validate	(value) => string \| string[] \| null	Returns an error message when the value is invalid.
validationMode	'onSubmit' \| 'onBlur' \| 'onChange'= 'onSubmit'	Determines when the field is validated.
render	React.ReactElement	On FieldControl, compose a custom control such as Input.
match	'customError' \| 'valueMissing' \| …	On FieldError, decides when the error message shows.
disabled	boolean= false	Disables the whole field.