Field

Labels, descriptions and errors for form controls.

Profile

Shown to other members of your team.

import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSet,
} from "@/components/ui/field";
import { Input } from "@/components/ui/input";
import { Textarea } from "@/components/ui/textarea";

export default function FieldFieldset() {
  return (
    <FieldSet className="w-full max-w-sm">
      <FieldLegend>Profile</FieldLegend>
      <FieldDescription>Shown to other members of your team.</FieldDescription>
      <FieldGroup>
        <Field>
          <FieldLabel>Full name</FieldLabel>
          <Input defaultValue="Ada Park" />
          <FieldDescription>Use the name people know you by.</FieldDescription>
        </Field>
        <Field>
          <FieldLabel>Bio</FieldLabel>
          <Textarea placeholder="A sentence or two about yourself" />
        </Field>
      </FieldGroup>
    </FieldSet>
  );
}

Installation

Add the registryOnce per project
pnpm dlx shadcn@latest registry add @jarvis=https://ui.jarv.is/r/{name}.json
Add field
pnpm dlx shadcn@latest add @jarvis/field

Usage

import { Checkbox } from "@/components/ui/checkbox";
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSeparator,
  FieldSet,
} from "@/components/ui/field";
import { Input } from "@/components/ui/input";

export function AccountForm() {
  return (
    <FieldSet>
      <FieldLegend>Account</FieldLegend>
      <FieldDescription>How we reach you.</FieldDescription>
      <FieldGroup>
        <Field>
          <FieldLabel>Email</FieldLabel>
          <Input type="email" />
          <FieldDescription>We send receipts here.</FieldDescription>
        </Field>
        <FieldSeparator />
        <Field orientation="horizontal">
          <Checkbox />
          <FieldContent>
            <FieldLabel>Marketing emails</FieldLabel>
            <FieldDescription>A few a year, at most.</FieldDescription>
          </FieldContent>
        </Field>
      </FieldGroup>
    </FieldSet>
  );
}

FieldSet groups related fields under a FieldLegend, and FieldGroup stacks them. Each Field holds one control with its label, description and error. FieldContent keeps a label and description together beside a control.

A Field links its parts to the control inside it, so the label names it and screen readers read the description and error with it, without any ids. Every control built on Base UI takes part, as do Textarea and NativeSelect. For the rest, such as DatePicker, point the FieldLabel at the control's id with htmlFor.

Outside a Field, FieldLabel is a plain label. Wrap a checkbox, radio or switch in it to label that control, or point it at one with htmlFor. An icon before its text is sized and dimmed to match.

In a Form, give each Field a name. The form submits the control's value under that name and validates it, and FieldError shows what went wrong.

Composition

FieldSet

Examples

Invalid

Set invalid on the field, which marks the control invalid too, and put the message in FieldError. It also takes an errors array of { message } objects, as form libraries return. Without either, FieldError shows the message from the field's own validation whenever it fails.

import { Field, FieldError, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";

export default function FieldInvalid() {
  return (
    <Field invalid className="max-w-sm">
      <FieldLabel>Username</FieldLabel>
      <Input defaultValue="ada park" />
      <FieldError>Use letters, numbers and dashes.</FieldError>
    </Field>
  );
}

Disabled

Set disabled on the field to disable its control and fade the label and description with it.

import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";

export default function FieldDisabled() {
  return (
    <Field disabled className="max-w-sm">
      <FieldLabel>Email</FieldLabel>
      <Input defaultValue="ada@example.com" />
      <FieldDescription>Managed by your organization.</FieldDescription>
    </Field>
  );
}

Horizontal

orientation="horizontal" puts the control and label in a row, in the order you write them.

Weekly digest

A summary of activity every Monday.

Product updates

News about features and improvements.

Tips and tutorials

Play a sound for new messages

import { Checkbox } from "@/components/ui/checkbox";
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldSeparator,
} from "@/components/ui/field";
import { Switch } from "@/components/ui/switch";

export default function FieldHorizontal() {
  return (
    <FieldGroup className="max-w-sm">
      <Field orientation="horizontal">
        <FieldContent>
          <FieldLabel>Weekly digest</FieldLabel>
          <FieldDescription>A summary of activity every Monday.</FieldDescription>
        </FieldContent>
        <Switch defaultChecked />
      </Field>
      <FieldSeparator />
      <Field orientation="horizontal">
        <Checkbox defaultChecked />
        <FieldContent>
          <FieldLabel>Product updates</FieldLabel>
          <FieldDescription>News about features and improvements.</FieldDescription>
        </FieldContent>
      </Field>
      <Field orientation="horizontal">
        <Checkbox />
        <FieldLabel>Tips and tutorials</FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <Switch size="sm" />
        <FieldLabel>Play a sound for new messages</FieldLabel>
      </Field>
    </FieldGroup>
  );
}

Radio group

Wrap each option of a radio or checkbox group in a FieldItem, which links its label and description to it. variant="label" makes a FieldLegend look like a label instead of a heading.

Send notifications to

Push notifications

Nothing

import { FieldItem, FieldLabel, FieldLegend, FieldSet } from "@/components/ui/field";
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";

export default function FieldRadioGroup() {
  return (
    <FieldSet className="w-full max-w-sm">
      <FieldLegend variant="label">Send notifications to</FieldLegend>
      <RadioGroup defaultValue="email">
        <FieldItem>
          <RadioGroupItem value="email" />
          <FieldLabel>Email</FieldLabel>
        </FieldItem>
        <FieldItem>
          <RadioGroupItem value="push" />
          <FieldLabel>Push notifications</FieldLabel>
        </FieldItem>
        <FieldItem>
          <RadioGroupItem value="none" />
          <FieldLabel>Nothing</FieldLabel>
        </FieldItem>
      </RadioGroup>
    </FieldSet>
  );
}

With a separator

FieldSeparator is a Separator spaced to sit between fields. Children put a label in the middle of it.

import { Button } from "@/components/ui/button";
import { Field, FieldGroup, FieldLabel, FieldSeparator } from "@/components/ui/field";
import { Input } from "@/components/ui/input";

export default function FieldWithSeparator() {
  return (
    <FieldGroup className="max-w-sm">
      <Field>
        <FieldLabel>Email</FieldLabel>
        <Input type="email" placeholder="ada@example.com" />
      </Field>
      <Button variant="primary">Continue</Button>
      <FieldSeparator>or</FieldSeparator>
      <Button variant="secondary">Continue with SSO</Button>
    </FieldGroup>
  );
}

Choice cards

Put a control and its FieldContent inside a FieldLabel to make the whole card clickable. Use FieldTitle for its title, since a label can't contain another label.

Email reports

A usage summary at the end of each month.

Slack alerts

A message when spending passes your limit.

import { Checkbox } from "@/components/ui/checkbox";
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldTitle,
} from "@/components/ui/field";

export default function FieldChoiceCards() {
  return (
    <FieldGroup className="max-w-sm gap-3">
      <Field orientation="horizontal">
        <FieldLabel>
          <FieldContent>
            <FieldTitle>Email reports</FieldTitle>
            <FieldDescription>A usage summary at the end of each month.</FieldDescription>
          </FieldContent>
          <Checkbox defaultChecked />
        </FieldLabel>
      </Field>
      <Field orientation="horizontal">
        <FieldLabel>
          <FieldContent>
            <FieldTitle>Slack alerts</FieldTitle>
            <FieldDescription>A message when spending passes your limit.</FieldDescription>
          </FieldContent>
          <Checkbox />
        </FieldLabel>
      </Field>
    </FieldGroup>
  );
}

Responsive

orientation="responsive" stacks the label and control until the FieldGroup is wide enough to put them side by side.

Language

Used for emails and the interface.

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
} from "@/components/ui/field";
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from "@/components/ui/select";

const languages = { en: "English", es: "Español", fr: "Français", de: "Deutsch" };

export default function FieldResponsive() {
  return (
    <FieldGroup className="max-w-xl">
      <Field orientation="responsive">
        <FieldContent>
          <FieldLabel>Language</FieldLabel>
          <FieldDescription>Used for emails and the interface.</FieldDescription>
        </FieldContent>
        <Select items={languages} defaultValue="en">
          <SelectTrigger>
            <SelectValue />
          </SelectTrigger>
          <SelectContent>
            {Object.entries(languages).map(([value, label]) => (
              <SelectItem key={value} value={value}>
                {label}
              </SelectItem>
            ))}
          </SelectContent>
        </Select>
      </Field>
    </FieldGroup>
  );
}

Props

Field has the group role, and FieldError the alert role. FieldError's match picks the failed check it shows for, as the Form page explains.

Part	Extends
FieldSet	Base UI's Fieldset.Root
FieldLegend	Base UI's Fieldset.Legend
FieldGroup	<div>
Field	Base UI's Field.Root
FieldItem	Base UI's Field.Item
FieldContent	<div>
FieldLabel	Base UI's Field.Label
FieldTitle	<div>
FieldDescription	Base UI's Field.Description
FieldSeparator	Separator
FieldError	Base UI's Field.Error

The tables leave out className, style and render. Parts built on Base UI take them as its styling and composition guides describe.

FieldLegend

Prop	Type	Default
`variant`	`"label" \| "legend"`	`"legend"`

Field

Prop	Type	Default
`disabled` Whether the component should ignore user interaction. Takes precedence over the `disabled` prop on the `<Field.Control>` component.	`boolean`	`false`
`name` Identifies the field when a form is submitted. Takes precedence over the `name` prop on the `<Field.Control>` component.	`string`	—
`validate` A function for custom validation. Return a string or an array of strings with the error message(s) if the value is invalid. Returning nothing, `null`, an empty string, or an empty array means the value is valid. Asynchronous functions are supported, but they do not prevent form submission when using `validationMode="onSubmit"`.	`((value: unknown, formValues: Form.Values) => string \| string[] \| null \| void \| Promise<string \| string[] \| null \| void>)`	—
`validationMode` Determines when the field should be validated. This takes precedence over the `validationMode` prop on `<Form>`. `onSubmit`: triggers validation when the form is submitted, and re-validates on change after submission. `onBlur`: triggers validation when the control loses focus. `onChange`: triggers validation on every change to the control value.	`"onBlur" \| "onChange" \| "onSubmit"`	`'onSubmit'`
`validationDebounceTime` How long to wait between `validate` callbacks if `validationMode="onChange"` is used. Specified in milliseconds.	`number`	`0`
`invalid` Whether the field is invalid. Useful when the field state is controlled by an external library.	`boolean`	—
`dirty` Whether the field's value has been changed from its initial value. Useful when the field state is controlled by an external library.	`boolean`	—
`touched` Whether the field has been touched. Useful when the field state is controlled by an external library.	`boolean`	—
`actionsRef` A ref to imperative actions. `validate`: Validates the field when called.	`React.RefObject<FieldRootActions \| null>`	—
`orientation`	`"horizontal" \| "responsive" \| "vertical"`	`"vertical"`

FieldItem

Prop	Type	Default
`disabled` Whether the wrapped control should ignore user interaction. The `disabled` prop on `<Field.Root>` takes precedence over this.	`boolean`	`false`

FieldLabel

Prop	Type	Default
`nativeLabel` Whether the component renders a native `<label>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a label (for example, `<div>`). This is useful to avoid inheriting label behaviors on `<button>` controls (such as `<Select.Trigger>` and `<Combobox.Trigger>`), including avoiding `:hover` on the button when hovering the label, and preventing clicks on the label from firing on the button.	`boolean`	`true`

FieldSeparator

Prop	Type	Default
`orientation` The orientation of the separator.	`"horizontal" \| "vertical"`	`"horizontal"`

FieldError

Prop	Type	Default
`match` Determines whether to show the error message according to the field's ValidityState. Specifying `true` will always show the error message, and lets external libraries control the visibility.	`boolean \| keyof ValidityState`	—
`errors` Messages to show, such as the errors a form library returns. Takes the place of `children`.	`({ message?: string; } \| undefined)[]`	—