Field

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add field

Usage#

Drop a control between FieldLabel and FieldHint. You never touch id, htmlFor, or aria-describedby - Field generates them with useId and hands them to the control through context. Clicking the label focuses the control, and screen readers announce the hint.

import { Field, FieldLabel, FieldHint } from "@/components/ui/field"
import { InputRoot, InputField } from "@/components/ui/input"

export function Example() {
  return (
    <Field>
      <FieldLabel>Email</FieldLabel>
      <InputRoot>
        <InputField type="email" />
      </InputRoot>
      <FieldHint>We'll only use it for account notifications.</FieldHint>
    </Field>
  )
}

Required & error#

Set required to append a destructive asterisk to the label. Set hasError on the Field - it cascades to the control’s border, sets aria-invalid, and turns the hint into the destructive error message. You set it in one place, not on every part.

Help behind an icon#

When the help is a nice-to-know rather than an instruction, and a form stacks enough fields that a line under each one doubles its height, pass it to info on the label instead of a FieldHint. It shows in a tooltip on an info icon, and screen readers still hear it as the control's description. Keep FieldHint for anything the person needs to read before typing, and for errors.

Validation#

Put the constraint on the control: required, type="email", pattern, minLength. Inside a Form, a failed submit shows the message in the field, focuses the first invalid control and shakes it. No browser bubble. FieldError with match gives each failure its own copy, and takes the hint's place while it shows.

Skip FieldError and the field shows the browser's own message. Leave out match and one FieldError shows whatever failed.

Custom validation#

validate runs once the native constraints pass. It gets the value and every value in the form, and returns a message, a list of them, or null.

Async validation#

Return a promise to check against your API. Pair it with validationDebounceTime so a request waits for a pause in typing. A stale answer never overwrites a newer one, and a submit waits for pending checks. data-validating is on the Field while one runs.

Field states#

The Field root carries its state as data attributes, so you can style anything inside it: data-invalid, data-valid, data-touched, data-dirty, data-filled, data-focused and data-validating.

<Field className="group/field">
  <FieldLabel className="group-data-focused/field:text-foreground">Email</FieldLabel>
  …
</Field>

Any control#

Field is control-agnostic. Because Input, Select, and PasswordInput all forward native props, the same wrapper labels any of them - the wiring lands on the right element automatically.

Two fields per row#

FieldRow places sibling fields side by side and stacks them on narrow viewports - the answer to Name · Surname pairs. It is pure layout, so it composes with any number of fields.

A whole form#

Wrap the fields in a Form, which owns the gap so no form has to invent its own, reach for FieldRow where two values belong together, and let each Field own its own wiring. This is a full registration form, name pair, email, country, and a password pair, with nothing wired by hand.

Shape#

Fields are rounded rectangles, not pills: sm 12, md 14 and lg 16, the same corner as an icon-only Button of that size. Any Button inside a <form> takes that corner too, so a submit button always matches the field beside it. The same Button outside a form stays a pill.

In a Dialog#

Field composes straight into a Dialog. The wiring flows through Radix's Portal because React context follows the component tree, not the DOM - so htmlFor, aria-describedby, and the hasError cascade all still work. The modal's own name comes from DialogTitle / DialogDescription (Radix), independent of the per-field labels. Try submitting with an invalid email to see the error cascade.

Disabled#

disabled on the Field dims the label and disables the control inside.

Field vs FieldGroup#

A Field wraps one control, because a label needs exactly one control to point at. When several controls answer a single question, a radio set or a cluster of checkboxes, there is nothing for the label to name, so the right wrapper is FieldGroup: a real fieldset with a real legend. It ships alongside Field and takes the same hasError, disabled, and required props, and the same FieldHint describes the whole group.

// One control: a Field.
<Field required>
  <FieldLabel>Email</FieldLabel>
  <InputRoot><InputField type="email" /></InputRoot>
</Field>

// Several controls, one question: a FieldGroup.
<FieldGroup required>
  <FieldGroupLabel>Email preferences</FieldGroupLabel>
  <RadioGroup>…</RadioGroup>
  <FieldHint>Pick at least one.</FieldHint>
</FieldGroup>

API reference#

FAQ#