Field

Groups a label, control, and description into an accessible form field. Built on Base UI's field primitive, which wires up labelling, native validation, and error announcement for the control inside.

Last updated January 1, 1980

CreditsModifiedPublished

Copied from shadcn/ui and coss/ui.

Added FieldItem, FieldControl, and FieldValidity exports following coss/ui's Field API — passthrough aliases for Base UI's parts so custom controls can register with the field context and validity state is reachable via render props

Overview

Installation

$ pnpm dlx shadcn@latest add @persianlabsui/field

Usage

import {
  Field,
  FieldDescription,
  FieldLabel,
} from "@/components/ui/field"
import { Input } from "@/components/ui/input"

<Field>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <Input id="email" type="email" />
  <FieldDescription>We'll never share your email.</FieldDescription>
</Field>

Input registers itself with the field automatically. Custom controls (like a plain textarea) need FieldControl, shown below.

Examples

Required

Native constraint validation drives the error — submit the empty field to see it.

Disabled

Set disabled on Field to dim the label and description; set it on the control to actually block input.

Error

Pass match={true} to show the error regardless of the field's internal validity, letting an external validation library (or your own state) control visibility.

Validity

FieldValidity exposes the live validity state via a render prop.

Input Group

Compose Input Group inside a Field for labelled, validated addon inputs.

Textarea

Textarea is a plain element, so wrap it in FieldControl to register it with the field context.

Checkbox

Nest the control inside FieldLabel for toggle-style fields.

Switch

Horizontal

Set orientation="horizontal" to place the label and control side by side, e.g. for a settings-style toggle row.

RTL

API Reference

FieldItem

Prop	Type	Default	Description
...props	FieldPrimitive.Item.Props	—	A flex container for grouping field content, passed through to Base UI's Field.Item.

FieldError

Prop	Type	Default	Description
match	boolean \| keyof ValidityState	—	Controls when the error shows. Pass true to always show it, letting an external validation library control visibility.

FieldControl / FieldValidity

Prop	Type	Default	Description
...props	FieldPrimitive.Control.Props	—	Alias for Base UI's Field.Control. Use it to register a custom or third-party control (e.g. a plain textarea) with the field context so it participates in labelling, validation, and error state.

See the Base UI Field docs for the full primitive API.

Edit this page on GitHub

PreviousEmpty NextHover Card