Field

The Field component family provides a structured way to compose accessible form fields. It handles the association between labels, inputs, descriptions, and error messages — ensuring proper ARIA attributes are applied automatically via React Aria's useField hook.

Use the primitive sub-components (Field, FieldLabel, FieldDescription, FieldError) for full control, or use ComposedField for a batteries-included wrapper.

Installation

npx @tailgrids/cli add field

Anatomy

Import the sub-components you need and compose them together.

import {
  FieldSet,
  FieldLegend,
  FieldGroup,
  Field,
  FieldContent,
  FieldLabel,
  FieldTitle,
  FieldDescription,
  FieldError,
  FieldSeparator,
  ComposedField
} from "@/registry/core/Field";

export const FieldAnatomy = () => (
  <FieldSet>
    <FieldLegend>Group Title</FieldLegend>
    <FieldGroup>
      <Field>
        <FieldLabel htmlFor="input-id">Label</FieldLabel>
        {/* Input, Select, Textarea, etc. */}
        <FieldDescription>Optional helper text.</FieldDescription>
        <FieldError>Validation message.</FieldError>
      </Field>

      <FieldSeparator />

      <Field orientation="horizontal">
        <FieldContent>
          <FieldTitle>Title</FieldTitle>
          <FieldDescription>Helper text.</FieldDescription>
        </FieldContent>
        {/* Input, Select, Textarea, etc. */}
      </Field>

      <ComposedField
        label="Label"
        description="Helper text"
        errorMessage="Error message"
        isInvalid
      >
        {/* Input, Select, Textarea, etc. */}
      </ComposedField>
    </FieldGroup>
  </FieldSet>
);

• Field is the core wrapper for a single field. Supports vertical, horizontal, and responsive orientations.
• FieldContent groups a label and description side by side with the control — useful in horizontal layouts.
• FieldGroup stacks multiple Field components with consistent spacing.
• FieldSet with FieldLegend provides semantic <fieldset> grouping.
• ComposedField uses React Aria's useField hook to automatically wire up ARIA attributes.

Examples

Input

Compose a Field with an Input to create a labeled text field with optional description and error state.

Textarea

The same composition pattern works with any form control, including TextArea.

Horizontal

Use orientation="horizontal" to place the label and control side by side. Wrap the label and description in FieldContent for proper alignment.

Fieldset

Use FieldSet, FieldLegend, and FieldGroup to semantically group related fields. Add FieldSeparator to visually divide sections.

Composed Field

The ComposedField component uses React Aria's useField hook under the hood to automatically generate IDs, associate labels with inputs via aria-labelledby, and link descriptions and errors with aria-describedby.

API Reference

FieldSet

Container that renders a semantic <fieldset> with spacing presets.

FieldLegend

Legend element for a FieldSet. Use the label variant to match label sizing in nested fieldsets.

FieldGroup

Layout wrapper that stacks Field components with consistent spacing. Enables container queries for responsive orientations.

Field

The core wrapper for a single field. Controls layout orientation and invalid state.

FieldContent

Flex column that groups elements like label and description. Useful when the label sits beside the control in horizontal layouts.

FieldLabel

Styled label element for form controls.

FieldTitle

Renders a title with label styling inside FieldContent. Useful for non-interactive labels.

FieldDescription

Helper text slot for providing context about a form field.

FieldError

Validation message slot, styled with error color.

FieldSeparator

Visual divider to separate sections inside a FieldGroup. Accepts optional inline content.

ComposedField

Fully composed field wrapper using React Aria's useField hook. Automatically handles aria-labelledby, aria-describedby, and ID generation.

Accessibility

• ARIA Linking: ComposedField uses React Aria's useField hook to automatically link the label, description, and error message to the form control via aria-labelledby and aria-describedby.
• Semantic HTML: FieldSet renders a native <fieldset> element, and FieldLegend renders a <legend>, providing semantic grouping that assistive technologies understand.
• Label Association: FieldLabel uses the native <label> element with htmlFor for proper click-to-focus behavior.
• Error States: FieldError communicates validation messages to screen readers through proper ARIA association when used within ComposedField.