Field

FreeNew

Form field layout with label, description and error that wire their ids to the control automatically, plus fieldset, legend, orientation and invalid/disabled state.

The full demo as documented.

Customize

Derived from this item’s props table, because it declares no controls of its own. Changes drive the preview live.

orientation

invalid

disabled

controlId

required

children

Guide and examples

Installation


pnpm dlx shadcn@latest add https://ui.tealmac.com/r/field.json

Usage

import {
  Field,
  FieldDescription,
  FieldError,
  FieldLabel,
  useFieldControl,
} from "@/components/ui/field"

function FieldInput(props: React.ComponentProps<typeof Input>) {
  return <Input {...useFieldControl()} {...props} />
}
 
;<Field invalid={!!error}>
  <FieldLabel required>Work email</FieldLabel>
  <FieldInput type="email" required />
  <FieldDescription>We send the invite here.</FieldDescription>
  <FieldError errors={[error]} />
</Field>

<FieldSet>
  <FieldLegend>Notifications</FieldLegend>
  <FieldGroup>
    <Field orientation="horizontal">
      <Switch {...useFieldControl()} />
      <FieldLabel>Email me about mentions</FieldLabel>
    </Field>
  </FieldGroup>
</FieldSet>

Props

Field

Prop	Type	Default	Description
`orientation`	`"vertical" \| "horizontal" \| "responsive"`	`"vertical"`	Layout of label and control. `horizontal` suits checkboxes and switches.
`invalid`	`boolean`	`false`	The label turns destructive, the control gets `aria-invalid` and the error is announced.
`disabled`	`boolean`	`false`	Disables the control and dims the field.
`controlId`	`string`	-	Overrides the generated id shared by the label, control, description and error.

Also accepts all <div> props.

FieldLabel

Prop	Type	Default	Description
`required`	`boolean`	`false`	Shows a required asterisk. Add `required` to the control as well.

FieldError

Prop	Type	Default	Description
`errors`	`Array<{ message?: string } \| string \| undefined>`	-	Messages to show. Duplicates are removed; several messages render as a list.
`children`	`ReactNode`	-	Custom content instead of `errors`.

useFieldControl

Returns { id, aria-invalid, aria-describedby, disabled } to spread on the control inside a Field. Returns an empty object outside one.

FieldSet, FieldLegend (variant: "legend" | "label"), FieldGroup, FieldContent, FieldTitle, FieldDescription and FieldSeparator accept the props of their underlying elements.

Notes

FieldGroup is a container query root, so orientation="responsive" switches to a row once the group is wide enough.