Skip to main content

Field

Pair a form control with its label, hint, and validation message using the field pattern.

Examples

Use Field.Root when you want a form control to share a label, hint, and validation state. Wrap one control per field. Field.Label and Field.Description provide the control’s label and accessible description; Input, Textarea, and Select.Field read that context.

Input and hint

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
We will send updates to this address.
field-input-demo.tsx
import { Field, Input } from '@uswds-tailwind/react'
export default function FieldInputDemo() {
return (
<Field.Root className="max-w-xs">
<Field.Label>Email address</Field.Label>
<Field.Description>We will send updates to this address.</Field.Description>
<Input type="email" />
</Field.Root>
)
}

Error message

Set invalid on Field.Root after validation. Field.ErrorMessage then appears, and the control receives aria-invalid and a description that includes the error. required and disabled on the root also reach the control.

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
Enter the address where we can reach you.
Enter a valid email address.
field-error-demo.tsx
import { Field, Input } from '@uswds-tailwind/react'
export default function FieldErrorDemo() {
return (
<Field.Root invalid className="max-w-xs">
<Field.Label>Email address</Field.Label>
<Field.Description>Enter the address where we can reach you.</Field.Description>
<Field.ErrorMessage>Enter a valid email address.</Field.ErrorMessage>
<Input type="email" />
</Field.Root>
)
}

Select

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
Choose how you would like a reply.
field-select-demo.tsx
import { Field, Select } from '@uswds-tailwind/react'
export default function FieldSelectDemo() {
return (
<Field.Root className="max-w-xs">
<Field.Label>Contact method</Field.Label>
<Field.Description>Choose how you would like a reply.</Field.Description>
<Select.Root>
<Select.Field defaultValue="">
<option value="" disabled>Select a method</option>
<option value="email">Email</option>
<option value="phone">Phone</option>
</Select.Field>
<Select.Icon />
</Select.Root>
</Field.Root>
)
}

Textarea

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
Include any details that will help us respond.
field-textarea-demo.tsx
import { Field, Textarea } from '@uswds-tailwind/react'
export default function FieldTextareaDemo() {
return (
<Field.Root className="max-w-xs">
<Field.Label>Message</Field.Label>
<Field.Description>Include any details that will help us respond.</Field.Description>
<Textarea />
</Field.Root>
)
}

Fieldset

Use Fieldset.Root to group related controls and Fieldset.Legend to name the group. Each nested Field.Root keeps its own label and control association.

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
Personal information
field-fieldset-demo.tsx
import { Field, Fieldset, Input } from '@uswds-tailwind/react'
export default function FieldFieldsetDemo() {
return (
<Fieldset.Root className="max-w-xs">
<Fieldset.Legend>Personal information</Fieldset.Legend>
<div className="space-y-4">
<Field.Root>
<Field.Label>First name</Field.Label>
<Input type="text" />
</Field.Root>
<Field.Root>
<Field.Label>Last name</Field.Label>
<Input type="text" />
</Field.Root>
</div>
</Fieldset.Root>
)
}

Component API

Wrap one form control in Root. Label, Description, and ErrorMessage share the control's validation state.

Root<div>

Supplies field state to nested controls.

PropTypeDescription
requiredbooleanRequires a value.
disabledbooleanDisables the control.
invalidbooleanShows an error state.
readOnlybooleanMakes the control read-only.
AttributeValuePurpose
data-disabledPresent when disabledStyle the disabled state.
data-invalidPresent when invalidStyle the error state.

Label<label>

Names the control.

AttributeValuePurpose
data-disabledPresent when disabledStyle the disabled state.
data-invalidPresent when invalidStyle the error state.

Description<div>

Provides hint text associated with the control.

ErrorMessage<div>

Provides error text when invalid.

AttributeValuePurpose
data-invalidPresent when invalidStyle the error state.

Fieldset.Root<fieldset>

Groups related fields under one legend.

PropTypeDescription
disabledbooleanDisables controls in the group.
invalidbooleanMarks the group invalid.

Fieldset.Legend<legend>

Names the group of controls.

Fieldset.Description<div>

Provides supporting text for the group.

Fieldset.ErrorMessage<div>

Displays group-level validation text.

Accessibility

Put one Input, Textarea, Select.Field, or other supported control inside each Field.Root. The field connects its label, hint, and error text to that control.