skrewww

Forms

Form Field

Form Field is a shared field wrapper for label, description, required indicator, and validation placement — not a visual input.

Figma naming reference: Form Field Wrapper. React implementation: FormField.

State (Default/Error) — composition wrapper

betaReact AvailableFigma AvailableDocs Partial
React last updated
2026-07-13
Documentation last updated
2026-06-01
Accessibility target
WCAG 2.2 AA (target)
Version
0.2.0-beta

Known open questions

  • Horizontal label layout is unresolved in Figma — vertical layout only.
  • React name is FormField; Figma name is Form Field Wrapper.

Live preview

FormField owns label, description, required indicator, and validation placement. Prefer complete field components (TextInput, Select) for most forms; use FormField directly for grouped controls.

Label + description + required

Visible to everyone in your workspace.

Advanced composition

Checkbox list under one field label

Choose what we should send you.

Error via complete field component

Enter a valid API key.

RadioGroup and Switch

Default role
Enable beta features

Purpose

Shared field chrome for label, description, required indicator, and validation output — wrapping any form control without duplicating field logic per control.

Anatomy

FormField = label + control slot + supporting text or ValidationMessage. The nested control owns its own input semantics.

Variants and states

default · error

When to use

Any control that needs a field label plus helper or error text above/below the control, such as Text Input, Select, or grouped Checkbox lists.

When not to use

Standalone Checkbox, Radio, or Switch instances that already include an inline label. Do not treat Form Field as a visual input.

Accessibility

Associates label text with the nested control through htmlFor/id or fieldset/legend patterns. Validation messages must be linked with aria-describedby.

Keyboard behavior

FormField does not introduce keyboard behavior — focus moves to the nested control using native tab order.

Common mistakes

Embedding label and error logic inside every control instead of composing FormField. Using Form Field as if it were a text input.

Properties

Label (text). Required (boolean). Helper Text (text). Control supplied as child render function.

Tokens used

semantic/text/primarysemantic/text/secondarysemantic/action/danger

Component API

PropTypeDefaultDescription
labelstring—Visible or visually hidden field label.
controlIdstring—Stable id passed to the nested control.
requiredbooleanfalseShows required indicator.
supportingTextstring—Helper/description linked with aria-describedby.
errorstring—Static validation message rendered through ValidationMessage.
children(args) => ReactNode—Render prop receiving controlId, describedBy, invalid.

React example

Copy React example
import { TextInput } from "@/components/ui/TextInput";

export function Example() {
  return (
    <TextInput
      label="Workspace name"
      supportingText="Visible to your team."
      placeholder="Acme Design"
    />
  );
}

Related components

Related tokens

Related concepts