Field

The React Field component helps you build form fields with labels, inputs, helper text, and error messages. It keeps everything connected and structured in one place.

It makes forms easier to build and more accessible by linking labels, descriptions, and errors to the input. For example, a field can show a label, helper text, and an error message for an email input.

Built with React Aria and styled using Tailwind CSS. It supports accessibility, proper form structure, and flexible layouts using simple sub-components.

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

• Label association: FieldLabel connects to form controls using htmlFor, so clicking the label focuses the input.
• ARIA linking: ComposedField automatically links the label, description, and error message to the input using ARIA attributes.
• Error messages: FieldError displays validation messages and connects them to the input so screen readers can announce them.
• Descriptions: FieldDescription provides helper text that gives additional context to users.
• Semantic grouping: Use FieldSet and FieldLegend to group related fields using native <fieldset> and <legend> elements.