Field

A set of composable form field components for building structured form layouts. Field wraps a single input with its label, description, and error message. FieldSet and FieldGroup organize multiple fields into logical sections with consistent spacing.

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

export default function FieldDemo() {
  return (
    <Field>
      <FieldLabel htmlFor="email">Email</FieldLabel>
      <Input id="email" type="email" placeholder="you@example.com" />
      <FieldDescription>We will never share your email.</FieldDescription>
    </Field>
  )
}

Anatomy

import {
  Field,
  FieldLabel,
  FieldTitle,
  FieldDescription,
  FieldError,
  FieldContent,
  FieldGroup,
  FieldSet,
  FieldLegend,
  FieldSeparator,
} from "@/components/ui/field"

<FieldGroup>
  <Field>
    <FieldLabel>Email</FieldLabel>
    <Input type="email" placeholder="you@example.com" />
    <FieldDescription>We'll never share your email.</FieldDescription>
  </Field>
  <Field>
    <FieldLabel>Password</FieldLabel>
    <Input type="password" />
  </Field>
</FieldGroup>

Examples

Vertical field (default)

<Field>
  <FieldLabel>Username</FieldLabel>
  <Input placeholder="Enter your username" />
  <FieldDescription>This is your public display name.</FieldDescription>
</Field>

Horizontal field

Set orientation="horizontal" to lay out the label and input side by side.

<Field orientation="horizontal">
  <FieldLabel>Notifications</FieldLabel>
  <Switch />
</Field>

With error message

Use FieldError with a children string or pass an errors array to render validation messages.

<Field data-invalid="true">
  <FieldLabel>Email</FieldLabel>
  <Input type="email" aria-invalid="true" />
  <FieldError>Please enter a valid email address.</FieldError>
</Field>

FieldSet with legend

Use FieldSet and FieldLegend to group related fields under a heading, ideal for <fieldset> semantics.

<FieldSet>
  <FieldLegend>Billing Address</FieldLegend>
  <FieldGroup>
    <Field>
      <FieldLabel>Street</FieldLabel>
      <Input />
    </Field>
    <Field>
      <FieldLabel>City</FieldLabel>
      <Input />
    </Field>
  </FieldGroup>
</FieldSet>

API Reference

Field

The root wrapper for a single form field. Renders a <div> with role="group".

Prop	Type	Default	Description
`orientation`	`"vertical" \| "horizontal" \| "responsive"`	`"vertical"`	Layout direction. `"responsive"` switches from vertical to horizontal at the `@md` container breakpoint.
`className`	`string`	—
`children`	`ReactNode`	—

FieldLabel

A <Label> component that wraps the label text for a field. Supports nesting a Field inside for card-like checkbox/radio patterns.

Prop	Type	Default
`className`	`string`	—
`children`	`ReactNode`	—

FieldTitle

A non-interactive title <div> for use when you need a field heading without a <label> element.

Prop	Type	Default
`className`	`string`	—
`children`	`ReactNode`	—

FieldDescription

A <p> element for helper text below the input.

Prop	Type	Default
`className`	`string`	—
`children`	`ReactNode`	—

FieldError

An alert <div> for displaying validation error messages. Accepts either children or an errors array.

Prop	Type	Default	Description
`errors`	`Array<{ message?: string } \| undefined>`	—	An array of error objects. Duplicate messages are deduplicated. If there is a single error, it renders as text; multiple errors render as a bulleted list.
`className`	`string`	—
`children`	`ReactNode`	—	When provided, takes precedence over `errors`.

FieldContent

A flex column <div> for wrapping the description and error below a checkbox or radio in horizontal layouts.

Prop	Type	Default
`className`	`string`	—
`children`	`ReactNode`	—

FieldGroup

A <div> that arranges multiple Field components in a vertical stack with consistent gap spacing. Supports @container queries for responsive field layouts.

Prop	Type	Default
`className`	`string`	—
`children`	`ReactNode`	—

FieldSet

A <fieldset> element for grouping related fields with a legend.

Prop	Type	Default
`className`	`string`	—
`children`	`ReactNode`	—

FieldLegend

A <legend> element rendered as a heading for a FieldSet.

Prop	Type	Default	Description
`variant`	`"legend" \| "label"`	`"legend"`	`"legend"` uses base font size, `"label"` uses the smaller label font size.
`className`	`string`	—
`children`	`ReactNode`	—

FieldSeparator

A horizontal divider between fields, with optional centered text content (e.g. "or").

Prop	Type	Default	Description
`children`	`ReactNode`	—	When provided, renders centered text over the separator line.
`className`	`string`	—