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>

With Label End

Password

Forgot password?

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

Label End With Hidden Label

Password

Forgot password?

<Field {...args}>
  <input id="field-story" placeholder="Password" type="password" />
</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.
isReadOnly	boolean	false	Whether the associated control is read-only.
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.
labelEnd	ReactNode	—	Content shown at the end of the label row, such as a "Forgot password?" link. It renders outside the label element, so interacting with it does not focus the control and it is not part of the control's accessible name. It stays visible when isLabelHidden is true, on a row of its own.
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.
isReadOnly	boolean	false	Whether the associated control is read-only.
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.
labelEnd	ReactNode	—	Content shown at the end of the label row, such as a "Forgot password?" link. It renders outside the label element, so interacting with it does not focus the control and it is not part of the control's accessible name. It stays visible when isLabelHidden is true, on a row of its own.
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.
isReadOnly	boolean	false	Whether the associated control is read-only.
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.
labelEnd	ReactNode	—	Content shown at the end of the label row, such as a "Forgot password?" link. It renders outside the label element, so interacting with it does not focus the control and it is not part of the control's accessible name. It stays visible when isLabelHidden is true, on a row of its own.
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	—