Field

The parts around a control: a label, a line of help, and an error that slides in under a small slanted mark. Validation is Base UI's.

Install

terminal

# once per project: where @zeroui items come frompnpm dlx shadcn@latest registry add @zeroui=https://zeroui.catforest.dev/r/{name}.jsonpnpm dlx shadcn@latest add @zeroui/field

Examples

Validating as you type

Callsign

Shown on every job you take.

field-validation.tsx

import {  Field,  FieldDescription,  FieldError,  FieldLabel,} from "@/components/zero/field";import { Input } from "@/components/zero/input";export default function FieldValidation() {  return (    <Field      className="w-full max-w-xs"      validationMode="onChange"      validate={(value) =>        typeof value === "string" && value.length > 0 && value.length < 3          ? "At least three characters."          : null      }    >      <FieldLabel>Callsign</FieldLabel>      <Input placeholder="Three or more characters" />      <FieldDescription>Shown on every job you take.</FieldDescription>      <FieldError />    </Field>  );}

Invalid from outside

Drop point

That pier closed last season.

field-invalid.tsx

import { Field, FieldError, FieldLabel } from "@/components/zero/field";import { Input } from "@/components/zero/input";export default function FieldInvalid() {  return (    <Field invalid className="w-full max-w-xs">      <FieldLabel>Drop point</FieldLabel>      <Input defaultValue="Pier 0" />      <FieldError match>That pier closed last season.</FieldError>    </Field>  );}

Behaviour

An Input or a Select inside a Field is its control: the label names it, and when the Field is invalid its outline turns to danger along with the label.

The error slides in on the reveal timing (240 ms) and leaves faster (140 ms). Give FieldError match to show it whenever the field is invalid, for validation done elsewhere.

Props

Field

Prop	Type	Default	Description
validate	(value) => string \| string[] \| null	—	Returns the error for a value, or null.
validationMode	"onSubmit" \| "onBlur" \| "onChange"	"onSubmit"	When validate runs.
invalid	boolean	—	Marks the field invalid from outside.

Also takes every prop of Base UI's Field.Root.

FieldLabel

Also takes every prop of Base UI's Field.Label.

FieldDescription

Also takes every prop of Base UI's Field.Description.

FieldError

Prop	Type	Default	Description
match	boolean \| keyof ValidityState	—	true shows the message whenever the field is invalid; a validity key shows it for that failure only.

Also takes every prop of Base UI's Field.Error.