Field

Field handles the structure around an input rather than the input itself. It gives labels, descriptions, legends, separators, and errors one consistent rhythm so forms stay legible when density increases or validation appears.

Installation

Purchase access, then open /account/install to issue a registry token.

Usage

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

<Field>
  <FieldLabel htmlFor="slug">Archive slug</FieldLabel>
  <FieldContent>
    <Input id="slug" />
    <FieldDescription>Used in the public URL.</FieldDescription>
    <FieldError>Enter a unique slug.</FieldError>
  </FieldContent>
</Field>

Why This Primitive Exists

Most forms fail at the surrounding structure, not the input itself. The field primitive standardizes that structure so the label column, helper copy, and error treatment remain composed across simple forms and denser settings panels.

• Use it when labels and supporting text need a stable relationship to the control.
• Use FieldSet, FieldLegend, and FieldSeparator to break large forms into readable groups.
• Avoid it when a component already owns its full layout and validation contract, such as the Form helper layer.

Examples

Basic Vertical Field

The default vertical layout is the right starting point for ordinary forms and modal tasks.

<Field>
  <FieldLabel htmlFor="name">Collection name</FieldLabel>
  <FieldContent>
    <Input id="name" />
    <FieldDescription>Use the published collection name.</FieldDescription>
  </FieldContent>
</Field>

Horizontal And Responsive Layouts

Orientation controls how the label and content share space. Use horizontal layouts when the page has enough width to support a scanning label column.

<Field orientation="horizontal">
  <FieldLabel htmlFor="owner">Approval owner</FieldLabel>
  <FieldContent>
    <Input id="owner" />
  </FieldContent>
</Field>

In Context

The full field family becomes more valuable when a settings card needs legends, separators, titles, and inline validation without custom spacing logic.

<FieldSet>
  <FieldLegend>Release settings</FieldLegend>
  <Field orientation="horizontal" data-invalid="true">
    <FieldLabel htmlFor="owner">Owner email</FieldLabel>
    <FieldContent>
      <Input id="owner" aria-invalid />
      <FieldError>Enter a complete address.</FieldError>
    </FieldContent>
  </Field>
</FieldSet>

Guidance

Use Field For Layout, Not State

• Field does not manage form state or ids for you.
• Use it with plain inputs when you want structural consistency without a form library.
• Pair it with Form when the control needs automatic accessibility wiring from validation state.

Choose Orientation By Density

• Use vertical for dialogs, drawers, and shorter forms.
• Use horizontal when the page has room for a left label column.
• Use responsive when the same form should stack on small screens and align in columns on larger ones.

Treat Supporting Copy As Part Of The Form

• Use FieldDescription to explain constraints before the user hits an error.
• Use FieldError for actionable problems, not long explanations.
• Group related settings with FieldSet, FieldLegend, and FieldSeparator instead of inserting ad hoc spacers.

API Reference

Core Exports

Field

Field also accepts normal div props such as data-invalid, id, and children.

FieldLegend

FieldError

All remaining exports forward their native element props directly.