Field

Usage

import { Field, FieldLabel, FieldDescription, FieldError, FieldValidity } from '@appica/ui-react/field'
import { Fieldset, FieldsetLegend } from '@appica/ui-react/fieldset'

<Field>
  <FieldLabel>Email</FieldLabel>
  <Input type="email" placeholder="you@example.com" />
  <FieldDescription>We'll send your receipt here.</FieldDescription>
</Field>

Field wires a label, description, and error message to one control without you having to juggle id/htmlFor/aria-describedby by hand. Drop any Appica form control inside it — Input, Textarea, NumberField, Select, Switch, and the rest are all Field-aware: they pick up the field's disabled and invalid state and contribute their value to validation.

Validation is built in. Give Field a validate function (or use the native constraints on the control) and render a FieldError to surface the message — no separate state needed. Use Fieldset to gather several related fields under a single legend, and to disable the whole group at once.

Examples

Default

A label sits above the control and a description below it. Field associates all three automatically — clicking the label focuses the control, and the description is announced as the control's aria-describedby.

import { Field, FieldLabel, FieldDescription } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'

export default function FieldDefault() {
  return (
    <Field className="w-full max-w-70">
      <FieldLabel>Email</FieldLabel>
      <Input type="email" placeholder="you@example.com" />
      <FieldDescription>We'll send your receipt here.</FieldDescription>
    </Field>
  )
}

Validation

Pass a validate callback that returns an error string (or an array of them) when the value is invalid, or null when it's fine. validationMode decides when it runs — onBlur here, or onChange / onSubmit. The returned message renders inside FieldError, and the control flips to its error styling via the field's invalid state.

'use client'

import { Field, FieldLabel, FieldDescription, FieldError } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'

export default function FieldValidation() {
  return (
    <Field
      className="w-full max-w-70"
      validationMode="onBlur"
      validate={(value) => {
        const email = String(value).trim()
        if (!email) return 'Email is required'
        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) return 'Enter a valid email address'
        return null
      }}
    >
      <FieldLabel>Email</FieldLabel>
      <Input type="email" placeholder="you@example.com" />
      <FieldDescription>Validates when the field loses focus.</FieldDescription>
      <FieldError />
    </Field>
  )
}

Disabled & read-only

Set disabled on the Field to disable the whole thing at once — it greys the control and takes it out of the tab order, propagating down to whatever control is inside. readOnly is a control-level concern (there's no field-wide equivalent), so set it on the input: it stays focusable and selectable but can't be edited.

import { Field, FieldLabel, FieldDescription } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'

export default function FieldDisabled() {
  return (
    <div className="flex w-full max-w-70 flex-col gap-5">
      <Field disabled>
        <FieldLabel>Email</FieldLabel>
        <Input type="email" defaultValue="you@example.com" />
        <FieldDescription>The whole field is disabled.</FieldDescription>
      </Field>
      <Field>
        <FieldLabel>API key</FieldLabel>
        <Input defaultValue="sk_live_8f2c91a4" readOnly />
        <FieldDescription>Focusable and selectable, but not editable.</FieldDescription>
      </Field>
    </div>
  )
}

Fieldset

Fieldset groups related fields under a FieldsetLegend and renders a native <fieldset> / <legend>. Setting disabled on the fieldset disables every control inside it in one move.

import { Fieldset, FieldsetLegend } from '@appica/ui-react/fieldset'
import { Field, FieldLabel } from '@appica/ui-react/field'
import { Input } from '@appica/ui-react/input'

export default function FieldFieldset() {
  return (
    <Fieldset className="w-full max-w-70">
      <FieldsetLegend>Shipping address</FieldsetLegend>
      <Field>
        <FieldLabel>Street</FieldLabel>
        <Input placeholder="123 Main St" />
      </Field>
      <Field>
        <FieldLabel>City</FieldLabel>
        <Input placeholder="Springfield" />
      </Field>
      <Field>
        <FieldLabel>Postal code</FieldLabel>
        <Input placeholder="12345" />
      </Field>
    </Fieldset>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

The label and description align to the start edge and the control follows the resolved direction. For setup details and caveats, see the RTL guide.

API reference

Field and Fieldset wrap Base UI's Field and Fieldset; every remaining prop is forwarded to the underlying element.

Field

The root that provides labelling and validation context to a single control. Renders a <div> and exposes data-valid / data-invalid / data-dirty / data-touched / data-filled / data-focused / data-disabled for styling.

FieldLabel

The control's label. Renders a <label> tied to the control, so clicking it moves focus.

FieldDescription

Supporting text for the control. Renders a <p> and is wired to the control's aria-describedby.

FieldError

The validation message. Renders only when the field is invalid (or match says so), with a height/opacity enter–exit transition that honours prefers-reduced-motion. With no children it shows the field's current error message; with match you supply custom children for a specific validity condition.

FieldValidity

A render-prop that exposes the field's live validity so you can render fully custom messaging.

Fieldset

Groups related fields. Renders a native <fieldset> (role="group") laid out as a column.

FieldsetLegend

The fieldset's heading. Renders a <legend> that names the group.

Accessibility

• FieldLabel renders a real <label> bound to the control, so the label is both clickable and announced — no manual htmlFor/id wiring.
• FieldDescription is linked through the control's aria-describedby, and FieldError is announced when it appears.
• Fieldset renders a native <fieldset> with role="group" named by its <legend>; disabled on it disables every descendant control.
• The error message's enter–exit transition honours prefers-reduced-motion.
• To label a group of controls (a RadioGroup, ToggleGroup, or a DateField/TimeField segment group) rather than a single input, don't use FieldLabel — a <label for> doesn't associate with a role="group". Name those with aria-labelledby pointing at a heading instead.