Field

A form field wrapper built on Base UI’s Field primitive. Provides label, description, error message, and validation state management for form controls like Input, Textarea, Checkbox, etc.

Import


import { Field } from "chunks-ui";

Basic Usage


<Field.Root>
  <Field.Label>Email</Field.Label>
  <Input type="email" placeholder="you@example.com" />
</Field.Root>

With Description


<Field.Root>
  <Field.Label>Password</Field.Label>
  <Field.Description>Must be at least 8 characters.</Field.Description>
  <Input type="password" />
</Field.Root>

Password

Must be at least 8 characters.

Validation Error

Set invalid on Field.Root to activate error styling. The input receives aria-invalid and data-invalid for red border styling. invalid alone does not show Field.Error: it renders only for a failed validation (see Native Validation), a server error passed to Form, or match={true}. To show a message for the invalid prop, add match:


<Field.Root invalid>
  <Field.Label>Email</Field.Label>
  <Input type="email" placeholder="you@example.com" />
  <Field.Error match>Please enter a valid email address.</Field.Error>
</Field.Root>

Please enter a valid email address.

With Textarea

Textarea works in a field the same way as Input: the label names it, the description describes it, and the field’s disabled and invalid state apply to it.


<Field.Root>
  <Field.Label>Message</Field.Label>
  <Field.Description>Describe your issue in detail.</Field.Description>
  <Textarea autoResize placeholder="Type here..." />
</Field.Root>

Message

Describe your issue in detail.

Native Validation

Use Field.Validity for native constraint validation:


<Field.Root>
  <Field.Label>Username</Field.Label>
  <Field.Control
    render={<Input />}
    required
    minLength={3}
  />
  <Field.Validity>
    {(state) =>
      state.validity.valueMissing ? (
        <Field.Error>Username is required.</Field.Error>
      ) : state.validity.tooShort ? (
        <Field.Error>Must be at least 3 characters.</Field.Error>
      ) : null
    }
  </Field.Validity>
</Field.Root>

Disabled State

Labels dim to 50% opacity and show a not-allowed cursor when the field is disabled:


<Field.Root disabled>
  <Field.Label>Locked Field</Field.Label>
  <Input disabled value="Cannot edit" />
</Field.Root>

Locked Field

Compound Parts

Part	Description
`Field.Root`	Wrapper element. Vertical flex with `gap-2`, so the control’s focus ring (4px past its edge) stays clear of the label and the text below. Manages `invalid` and `disabled` state.
`Field.Label`	Form label. `text-sm font-medium`. Dims and shows a not-allowed cursor when disabled.
`Field.Description`	Help text below the label. `text-xs text-muted-foreground`.
`Field.Error`	Error message. `text-xs text-destructive-text`. Renders on a failed validation, a server error, or with `match`.
`Field.Control`	Connects a form control to the field (for native validation). Uses `render` prop.
`Field.Validity`	Render prop for accessing native validity state.

Props

All Field parts are pass-throughs to the underlying Base UI Field.