Field

A compound component for building accessible form fields with labels, descriptions, validation errors, and control binding. Wraps Base UI's Field primitive with Patch UI styling.

$npx shadcn add @patchui/field

Basic Field

Username

Choose a unique username for your account.

Required with FieldControl

We'll use this to send notifications.

Error State

Password

Must be at least 8 characters.

Disabled

Organization

This field cannot be changed.

Usage

import {
  Field,
  FieldLabel,
  FieldDescription,
  FieldError,
  FieldControl,
  Input,
} from "@patchui/react";
 
// Basic field with Input
<Field>
  <FieldLabel>Username</FieldLabel>
  <FieldDescription>Choose a unique username.</FieldDescription>
  <Input placeholder="e.g. jane_doe" />
</Field>
 
// With native FieldControl and validation
<Field>
  <FieldLabel>Email</FieldLabel>
  <FieldControl type="email" placeholder="you@example.com" required />
  <FieldError />
</Field>
 
// Error state (controlled externally)
<Field invalid>
  <FieldLabel>Password</FieldLabel>
  <Input type="password" />
  <FieldError>Password must be at least 8 characters.</FieldError>
</Field>

Props

Field

Prop	Type	Default	Description
name	string	-	Identifies the field when a form is submitted. Takes precedence over the name on FieldControl.
invalid	boolean	false	Marks the field as invalid. Useful when field state is controlled externally.
disabled	boolean	false	Disables the field and its control, preventing interaction.
validate	(value, formValues) => string \| string[] \| null	-	Custom validation function. Return error message(s) if invalid, or null if valid. Async functions are supported.
validationMode	"onSubmit" \| "onBlur" \| "onChange"	"onSubmit"	When to trigger validation. Takes precedence over Form's validationMode.
validationDebounceTime	number	0	Debounce interval (ms) for validate callbacks when using onChange mode.
className	string	-	Additional CSS classes to apply to the field container.

FieldLabel

Prop	Type	Default	Description
children	ReactNode	-	The label text content. Automatically associated with the field control via accessibility attributes.
className	string	-	Additional CSS classes.

FieldDescription

Prop	Type	Default	Description
children	ReactNode	-	Help text displayed below the label. Connected to the field control via aria-describedby.
className	string	-	Additional CSS classes.

FieldError

Prop	Type	Default	Description
children	ReactNode	-	Custom error message. If omitted, displays the browser's native validation message.
className	string	-	Additional CSS classes.

FieldControl

Prop	Type	Default	Description
onValueChange	(value: string, details) => void	-	Callback fired when the value changes. Use when the control value is managed externally.
defaultValue	string	-	The initial value of the control.
className	string	-	Additional CSS classes.

FieldValidity

Prop	Type	Default	Description
children	(state: FieldValidityState) => ReactNode	-	Render function receiving the field's validity state (validity, error, errors, value).

FieldItem

Prop	Type	Default	Description
children	ReactNode	-	Content to render inside the field item. Used for grouping within checkbox/radio field groups.
className	string	-	Additional CSS classes.

Notes

Automatic labeling: FieldLabel and FieldDescription are automatically connected to the field control via aria-labelledby and aria-describedby.
FieldControl vs Input: You can use either the native FieldControl (renders an <input>) or any Base UI input component (Input, Checkbox, Select, etc.) as the field's control - they integrate with Field automatically.
FieldValidity: Use as a render prop to access the field's full validity state for custom validation UI.
FieldItem: Used inside Field to group checkbox or radio items when building multi-option field groups.
Validation modes: Set validationMode on Field to control when validation fires. "onSubmit" (default) validates on form submit, "onBlur" on focus loss, and "onChange" on every keystroke.