Field

A form field wrapper that renders a label, description, control slot, and validation status.

Examples

Default

EmailWe'll never share your email.

<Field {...args} description="We'll never share your email.">
  <input id="field-story" />
</Field>

Required

Email · Required

<Field {...args}>
  <input id="field-story" />
</Field>

Optional

Email · Optional

<Field {...args}>
  <input id="field-story" />
</Field>

Disabled

Email

<Field {...args}>
  <input disabled id="field-story" />
</Field>

Label Hidden

EmailThe label is visually hidden but still accessible.

<Field {...args}>
  <input id="field-story" placeholder="Email" />
</Field>

Label as span

Preference

Email Phone

<Field {...args}>
  <div aria-labelledby="pref-label" role="radiogroup">
    <label>
      <input name="pref" type="radio" /> Email
    </label>
    <label>
      <input name="pref" type="radio" /> Phone
    </label>
  </div>
</Field>

With Label Icon

Email

<Field {...args}>
  <input id="field-story" />
</Field>

With Label Tooltip

Email

We use this to send account notifications.

<Field {...args}>
  <input id="field-story" />
</Field>

Status — error

Email

This field is required.

<Field {...args}>
  <input id="field-story" />
</Field>

Status — warning

Email

This email is already in use.

<Field {...args}>
  <input id="field-story" />
</Field>

Status — success

Email

Email is available.

<Field {...args}>
  <input id="field-story" />
</Field>

Status — detached

Email

This field is required.

<Field {...args}>
  <input id="field-story" />
</Field>

Kitchen Sink

Email · Required

Used for account recovery and notifications.

Your primary contact email.

Please enter a valid email.

<Field {...args}>
  <input id="field-story" />
</Field>

API

Field

A form field wrapper that renders a label, description, control slot, and validation status.

When isOptional: false, isRequired: false

Prop	Type	Default	Description
children*	ReactNode	—	The form control rendered inside the field.
className	string	—	Additional CSS class names applied to the root element.
data-testid	string	—	Test ID applied to the root element.
description	ReactNode	—	Supporting text rendered between the label and control.
descriptionID	string	—	ID for the description element.
inputId*	string	—	ID of the associated control.
isDisabled	boolean	false	Whether the associated control is disabled.
isLabelHidden	boolean	false	Whether to visually hide the label and description.
label*	string	—	Field label text.
labelAs	'label' | 'span'	'label'	HTML element used for the label. Use 'span' for group controls (e.g., radiogroup) where htmlFor cannot target a labelable element.
labelIcon	IconComponent	—	Optional icon shown before the label.
labelId	string	—	ID applied to the label element, useful for aria-labelledby.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the root element.
status	FieldStatus	—	Validation status displayed below the control.
statusVariant	"attached" | "detached"	'attached'	How the status message is positioned.
style	CSSProperties	—	Inline styles applied to the root element.
isOptional	false	—
isRequired	false	—

When isOptional: true, isRequired: false

Prop	Type	Default	Description
children*	ReactNode	—	The form control rendered inside the field.
className	string	—	Additional CSS class names applied to the root element.
data-testid	string	—	Test ID applied to the root element.
description	ReactNode	—	Supporting text rendered between the label and control.
descriptionID	string	—	ID for the description element.
inputId*	string	—	ID of the associated control.
isDisabled	boolean	false	Whether the associated control is disabled.
isLabelHidden	boolean	false	Whether to visually hide the label and description.
label*	string	—	Field label text.
labelAs	'label' | 'span'	'label'	HTML element used for the label. Use 'span' for group controls (e.g., radiogroup) where htmlFor cannot target a labelable element.
labelIcon	IconComponent	—	Optional icon shown before the label.
labelId	string	—	ID applied to the label element, useful for aria-labelledby.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the root element.
status	FieldStatus	—	Validation status displayed below the control.
statusVariant	"attached" | "detached"	'attached'	How the status message is positioned.
style	CSSProperties	—	Inline styles applied to the root element.
isOptional*	true	—
isRequired	false	—

When isOptional: false, isRequired: true

Prop	Type	Default	Description
children*	ReactNode	—	The form control rendered inside the field.
className	string	—	Additional CSS class names applied to the root element.
data-testid	string	—	Test ID applied to the root element.
description	ReactNode	—	Supporting text rendered between the label and control.
descriptionID	string	—	ID for the description element.
inputId*	string	—	ID of the associated control.
isDisabled	boolean	false	Whether the associated control is disabled.
isLabelHidden	boolean	false	Whether to visually hide the label and description.
label*	string	—	Field label text.
labelAs	'label' | 'span'	'label'	HTML element used for the label. Use 'span' for group controls (e.g., radiogroup) where htmlFor cannot target a labelable element.
labelIcon	IconComponent	—	Optional icon shown before the label.
labelId	string	—	ID applied to the label element, useful for aria-labelledby.
labelTooltip	ReactNode	—	Tooltip content shown next to the label.
ref	Ref<HTMLDivElement>	—	Ref forwarded to the root element.
status	FieldStatus	—	Validation status displayed below the control.
statusVariant	"attached" | "detached"	'attached'	How the status message is positioned.
style	CSSProperties	—	Inline styles applied to the root element.
isOptional	false	—
isRequired*	true	—