Field

Field is the layout wrapper that wires a form control to its label, helper description, and validation message. Instead of hand-aligning a label, input, and error, you compose Field from its slotted parts so every form across Helm shares the same spacing, invalid styling, and accessibility wiring.

Live demo

The interactive story below runs from the deployed Storybook.

Usage

Source: field.tsx

import {
  FieldGroup,
  Field,
  FieldLabel,
  FieldDescription,
  FieldError,
  Input,
} from "@beacon/design-system";

// A single field with label and helper text.
<FieldGroup>
  <Field>
    <FieldLabel>Email address</FieldLabel>
    <Input type="email" placeholder="you@example.com" />
    <FieldDescription>We'll never share your email.</FieldDescription>
  </Field>
</FieldGroup>

// Invalid state: set data-invalid and render a FieldError.
<FieldGroup>
  <Field data-invalid="true">
    <FieldLabel>Username</FieldLabel>
    <Input defaultValue="johndoe" />
    <FieldError>Username is already taken.</FieldError>
  </Field>
</FieldGroup>

Parts

Part	Role
`Field`	A single field row. `orientation` is `"vertical"` (default), `"horizontal"`, or `"responsive"`. Set `data-invalid="true"` to switch on invalid styling.
`FieldLabel`	The label for the control; renders a `Label`. Wrapping a nested `Field` turns it into a selectable card label.
`FieldContent`	Optional column that groups the control plus its description and error (used for checkbox and radio layouts).
`FieldTitle`	Title text inside a `FieldContent`, for selectable options that have a heading and supporting text.
`FieldDescription`	Muted helper text below the control.
`FieldError`	Validation message with alert role. Pass `children`, or an `errors` array of `{ message }` objects to render one message or a bulleted list.
`FieldGroup`	Container that stacks multiple `Field` rows with consistent spacing.
`FieldSet`	Native `<fieldset>` wrapper for a related group of fields.
`FieldLegend`	The `<legend>` for a `FieldSet`; `variant` is `"legend"` (default) or `"label"`.
`FieldSeparator`	A horizontal divider between fields, with optional centered label content.

When to use

Every labeled form control: pair the label, control, helper text, and error in one consistent block.
Grouping related controls with FieldSet and FieldLegend (for example an address block).
Horizontal or responsive label layouts via the orientation prop.

Do not scatter a bare Label and control with manual margins. Compose them inside Field so spacing, invalid styling, and the error region stay consistent. The control itself is still an Input, Textarea, Checkbox, or similar primitive.