Field

Coordinate a control, its label and validation state.

Preview

Assistant name

Visible to everyone in this workspace.

Design guidance

Use Field when a control needs a coordinated label, help or validation state. Field.Label keeps Base UI's control association and accepts the same visual required and optional markers as Label. Controls own native constraints. Participating controls such as Input receive label, description and error associations from Field. Use Label when your existing form already owns those relationships.

Choose a placement for the content. Top works for most forms. Left labels stack at narrow widths. IFTA labels stay static inside a control at least 60px high. Placeholder placement hides the visible label but keeps it available to assistive technology.

Installation

Install

npx shadcn@latest add https://ghost-ui.com/r/field.json

Field examples also use the input, select and textarea registry items. Select and textarea remain optional compositions.

Basic usage

Input already participates in Field. Use it directly; reserve Field.Control render composition for a native or custom control that needs registration.

12345678import { Field } from "@/components/ui/field";
import { Input } from "@/components/ui/input";

<Field.Root>
<Field.Label>Email</Field.Label>
<Input type="email" />
<Field.Description>Used for account notices.</Field.Description>
</Field.Root>

Structures

Field.Root owns placement and field state. Field.Label names its registered control. Field.Control is optional when a composed control already participates in Base UI Field; use its render prop for native controls such as Textarea. Field.Description and Field.Error automatically associate their generated IDs with the control. Field.Validity exposes Base UI validity state. Field.Item labels an individual option in a Field-managed group, such as a checkbox group. Use Fieldset to group separate fields.

Examples

Subtle field

Set variant="subtle" on Field.Root to coordinate Input or Field.Control with its label. An explicit control or label variant overrides the inherited appearance. Field continues to own label, help, disabled and validation relationships.

Project name

Required

The marker is visual. The input still needs native required for browser validity.

Assistant name

Optional

Show optional status without changing control validity.

Assistant name

Disabled

Disable the root field so Base UI carries disabled state to its parts and control.

Assistant name

Native validation

Clear the required input and blur to show its missing-value error. Enter a value and blur again to recover.

Assistant name

Top placement

The default placement keeps the label above its control.

Assistant name

Visible to everyone in this workspace.

Left placement

Use this layout for short labels. At narrow widths, the label and control stack.

Assistant name

In-field top-aligned label

Keep the label static inside a control with at least 60px of height.

Assistant name

Placeholder presentation

This placement hides the label visually. The caller supplies placeholder text; use it only when surrounding context keeps the purpose clear after a value is entered.

Search sources

Textarea

Use Field.Control's render prop so a native Textarea participates in field registration.

System instructions

Select

Select uses a button trigger, so render a non-native Field.Label and give the trigger an explicit ID. This connects both its accessible name and label activation. The trigger keeps Select's 32px control height.

Response length

Caller-controlled error

Use this when application state owns validation. The example clears the collision while editing and checks it again on blur. Field.Error match displays the caller's message without adding a second validator.

Assistant name

This assistant name is already in use.

Full width

Let the field fill its available container width.

Assistant name

Caller-owned title

Field owns the visible label. Input owns editing. The caller owns the value.

Title

API reference

For inherited behavior and additional part properties, see the Base UI Field API.

Field.Root properties
Prop	Type	Default	Description
`variant`	`"outline" \| "subtle"`		Coordinates Input, Field.Control, Label and Signature appearance. Omit to preserve their defaults.
`className`	`string \| ((state: FieldRootState) => string)`		CSS class applied to the element, or a function that returns a class based on its state.
`style`	`CSSProperties \| ((state: FieldRootState) => React.CSSProperties)`		Style applied to the element, or a function that returns a style object based on its state.
`disabled`	`boolean`	`false`	Whether the component should ignore user interaction. Takes precedence over the disabled prop on Field.Control.
`invalid`	`boolean`	`undefined`	Marks an application-controlled field invalid.
`name`	`string`		Identifies the field when a form is submitted. Takes precedence over the name prop on Field.Control.
`render`	`ReactElement \| ComponentRenderFn`		Replace the root element or compose it with another component.
`actionsRef`	`RefObject<FieldRootActions \| null>`		Ref to imperative actions, including validate.
`validate`	`(value, formValues) => string \| string[] \| null \| void \| Promise<...>`		Caller-owned validation callback. Return a message to mark the value invalid.
`validationMode`	`FormValidationMode`	`'onSubmit'`	Validate on submit, blur, or change.
`validationDebounceTime`	`number`	`0`	Delay validation callbacks when validationMode is onChange.
`dirty`	`boolean`		Controlled dirty state.
`touched`	`boolean`		Controlled touched state.
`fullWidth`	`boolean`	`false`	Fill the available width when the control supports full width.
`placement`	`FieldPlacement`	`"top"`	Label placement: top, ifta, left, or placeholder.

Field.Label properties
Prop	Type	Default	Description
`required`	`boolean`	`false`	Show a visual required marker; native validation belongs to the control.
`optional`	`boolean`	`false`	Show a visual optional marker when required is false.
`className`	`string \| ((state) => string)`		Class name or state function forwarded to Base UI.
`render`	`ReactElement \| ComponentRenderFn`		Replace the label element. Pair a non-label render with nativeLabel={false}.
`nativeLabel`	`boolean`	`true`	Use native label behavior and association. Set false for button-based controls.
`ref / style / native attributes`	`Base UI Field.Label props`		Forwarded to Base UI Field.Label.

Field.Control properties
Prop	Type	Default	Description
`render`	`ReactElement \| ComponentRenderFn`		Register a native or custom control such as Textarea. Input already participates and is used directly.
`id / ref / native attributes`	`Base UI Field.Control props`		Forwarded to the registered control.

Field.Description properties
Prop	Type	Default	Description
`id`	`string`		Optional explicit ID; Field associates it with the control automatically.
`render / ref / native attributes`	`Base UI Field.Description props`		Forwarded to the description element.

Field.Error properties
Prop	Type	Description
`match`	`boolean \| ValidityState key`	Choose a native validity condition, or true to display a caller-controlled message. Pass children to supply the text; otherwise Base UI uses its validation message.
`id`	`string`	Optional explicit ID; Field connects the displayed message to the control automatically.
`render / ref / native attributes`	`Base UI Field.Error props`	Forwarded to the error element.

Field.Validity and Field.Item
Prop	Type	Default	Description
`Field.Validity`	`Base UI Field.Validity part`		Expose the field's native validity state and message.
`Field.Item`	`Base UI Field.Item part`		Label an individual option in a Field-managed control group.