Forms

Field

Form-field layout primitive. Standardises the label + control + description + error stack with consistent spacing and ARIA wiring.

Source

Preview

GitHub

import {
  Field,
  FieldDescription,
  FieldLabel,
} from '@brika/clay/components/field';
import { Input } from '@brika/clay/components/input';

/** Single field with label, control, and helper description. */
export default function FieldBasicDemo() {
  return (
    <Field>
      <FieldLabel htmlFor="email">Email</FieldLabel>
      <Input id="email" type="email" placeholder="you@example.com" />
      <FieldDescription>We'll never share your email.</FieldDescription>
    </Field>
  );
}

01 Installation

Install

Pull Field from the barrel for everyday use, or the granular path when you want a tighter bundle.

tsxBarrel1 line

import { Field } from "@brika/clay";

tsxGranular1 line

import { Field } from "@brika/clay/components/field";

02 Usage

A minimal example

Drop this into a page. Native HTML attributes pass through to the underlying primitive.

tsxField.tsx17 lines

import {
  Field,
  FieldDescription,
  FieldLabel,
} from '@brika/clay/components/field';
import { Input } from '@brika/clay/components/input';

/** Single field with label, control, and helper description. */
export default function FieldBasicDemo() {
  return (
    <Field>
      <FieldLabel htmlFor="email">Email</FieldLabel>
      <Input id="email" type="email" placeholder="you@example.com" />
      <FieldDescription>We'll never share your email.</FieldDescription>
    </Field>
  );
}

03 Examples

Field, every way

Checkbox

Inline checkbox + label pattern using `Field` with row layout.

GitHub

import { Checkbox } from '@brika/clay/components/checkbox';
import {
  Field,
  FieldDescription,
  FieldLabel,
} from '@brika/clay/components/field';
/** Inline checkbox + label pattern using `Field` with row layout. */
export default function FieldCheckboxDemo() {
  return (
    <Field className="flex-row items-start gap-2">
      <Checkbox id="terms" />
      <div className="flex flex-col gap-1">
        <FieldLabel htmlFor="terms" className="font-normal">
          Accept terms and conditions
        </FieldLabel>
        <FieldDescription>
          You agree to our Terms of Service and Privacy Policy.
        </FieldDescription>
      </div>
    </Field>
  );
}

Error

Invalid state pairs `aria-invalid` on the control with `<FieldError>`.

GitHub

import {
  Field,
  FieldError,
  FieldLabel,
} from '@brika/clay/components/field';
import { Input } from '@brika/clay/components/input';

/** Invalid state pairs `aria-invalid` on the control with `<FieldError>`. */
export default function FieldErrorDemo() {
  return (
    <Field>
      <FieldLabel htmlFor="email-error">Email</FieldLabel>
      <Input
        id="email-error"
        type="email"
        aria-invalid="true"
        placeholder="you@example.com"
      />
      <FieldError>Email is required.</FieldError>
    </Field>
  );
}

Group

`FieldGroup` stacks multiple fields with consistent vertical rhythm.

GitHub

import {
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
} from '@brika/clay/components/field';
import { Input } from '@brika/clay/components/input';
import { Textarea } from '@brika/clay/components/textarea';

/** `FieldGroup` stacks multiple fields with consistent vertical rhythm. */
export default function FieldGroupDemo() {
  return (
    <FieldGroup>
      <Field>
        <FieldLabel htmlFor="group-name">Name</FieldLabel>
        <Input id="group-name" placeholder="Ada Lovelace" />
      </Field>
      <Field>
        <FieldLabel htmlFor="group-email">Email</FieldLabel>
        <Input
          id="group-email"
          type="email"
          placeholder="ada@example.com"
        />
      </Field>
      <Field>
        <FieldLabel htmlFor="group-message">Message</FieldLabel>
        <Textarea id="group-message" placeholder="Tell us more..." />
        <FieldDescription>Markdown is supported.</FieldDescription>
      </Field>
    </FieldGroup>
  );
}

Set

`FieldSet` + `FieldLegend` group related controls semantically.

GitHub

import {
  Field,
  FieldDescription,
  FieldLabel,
  FieldLegend,
  FieldSet,
} from '@brika/clay/components/field';
import { RadioGroup, RadioGroupItem } from '@brika/clay/components/radio-group';

/** `FieldSet` + `FieldLegend` group related controls semantically. */
export default function FieldSetDemo() {
  return (
    <FieldSet>
      <FieldLegend>Notification frequency</FieldLegend>
      <FieldDescription>Choose how often you'd like updates.</FieldDescription>
      <RadioGroup defaultValue="weekly">
        <Field className="flex-row items-center gap-2">
          <RadioGroupItem id="freq-realtime" value="realtime" />
          <FieldLabel htmlFor="freq-realtime" className="font-normal">
            Real-time
          </FieldLabel>
        </Field>
        <Field className="flex-row items-center gap-2">
          <RadioGroupItem id="freq-daily" value="daily" />
          <FieldLabel htmlFor="freq-daily" className="font-normal">
            Daily digest
          </FieldLabel>
        </Field>
        <Field className="flex-row items-center gap-2">
          <RadioGroupItem id="freq-weekly" value="weekly" />
          <FieldLabel htmlFor="freq-weekly" className="font-normal">
            Weekly summary
          </FieldLabel>
        </Field>
      </RadioGroup>
    </FieldSet>
  );
}

04 Accessibility

Accessibility

Always associate FieldLabel with its control via htmlFor matching the input id.
Wire aria-describedby on the control to FieldDescription/FieldError ids when present so assistive tech announces helper and error copy.
Use FieldSet + FieldLegend (semantic <fieldset>/<legend>) to group related controls such as radio options.
FieldError should set role="alert" (default here) so dynamically appearing validation messages are announced.

05 Tokens 5 theme-overridable

Theme tokens

Every CSS variable Field reads, with its default and the dotted path you'd write in a ThemeConfig JSON to override it. Set any of these in your theme to retune Field without touching component code.

Field tokens

5 tokens

ColorFill, border, and text colors.4

--field-description-colorcolorvar(--muted-foreground)
components.field.descriptionColor
Text color of the supporting description copy below the control.
--field-error-colorcolorvar(--destructive)
components.field.errorColor
Text color of the validation error message rendered by `FieldError`.
--field-legend-colorcolorvar(--foreground)
components.field.legendColor
Text color of the `FieldLegend` heading inside a `FieldSet`.
--field-separator-colorcolorvar(--border)
components.field.separatorColor
Line color of the optional `FieldSeparator` divider.

GeometrySizes, lengths, and corner radii.1

--field-gapsizecalc(var(--spacing) * 1.5)
components.field.gap
Gap between adjacent children inside the field.

Override in a theme

Authoring a theme is plain JSON. Drop overrides under components.field, the names are camelCase versions of the variable suffix.

jsonmy-theme.json12 lines

{
  "id": "my-theme",
  "name": "My Theme",
  "description": "...",
  "accentSwatches": ["#000"],

  "components": {
    "field": {
      "descriptionColor": "var(--muted-foreground)"
    }
  }
}

Then apply with applyTheme(myTheme) (see the theming guide), scope it to a subtree with themeToCssVars(myTheme, mode), or consume any token directly in your own JSX with the matching Tailwind utility (e.g. bg-field-…) — see the chips on each token row.

06 API reference

API reference

Props specific to Field. Native HTML attributes pass through to the underlying primitive, see the component source on GitHub for the full type signature.