Field for React Aria

The label, the input or choice, and the line of help or error under it.

Use it when a control needs a label, a description, or an error. A prefix or a button on the input is an Input Group, not another caption. In React, React Aria handles the layout and the accessible name, not validation.

Installation

Anatomy

Usage

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

const FieldDemo = () => (
  <Field className="max-w-xs">
    <FieldLabel>Name</FieldLabel>
    <Input placeholder="Evil Rabbit" type="text" />
    <FieldDescription>This is your public display name.</FieldDescription>
  </Field>
);

Accessibility

Demos

Input

Password, with the rule above the box: at least 8 characters. Put FieldDescription before the control when people need the constraint before they type. The hero does the opposite and parks the hint underneath, which suits a note they can ignore. The input's type is password, so the characters stay masked while the rule stays readable.

Textarea

Feedback is a four-row textarea with a label and no helper line. The placeholder is the only hint, and it disappears once someone types, so use that only when the prompt is disposable. A rule that still matters after focus belongs in FieldDescription. A second paragraph under an already tall field is easy to miss.

Select

Department is chosen from engineering, design, or marketing rather than typed. The field label names the question, and the select keeps a placeholder until a value is picked. Use this for any short closed list in a form. A job title people invent goes back to a text input, with the label still outside the control so it stays visible after a choice.

Slider

Volume starts at 40, with the field label as the only caption. A slider often has no text of its own, so this is what makes the drag mean something. The control also carries its own accessible name. Drop that if the field label is already associated, or the name is read twice, and use a slider for a range rather than a number that has to be exact.

Fieldset

Street and city sit under one Address legend. FieldSet and FieldLegend are the wrap when several inputs answer a single question, the way a mailing address does. Each inner field still has its own label. The legend is announced with those labels and does not replace them, so two unrelated inputs do not need a set.

Checkbox

Same as shipping address starts checked, box and label in one horizontal row. Set orientation to horizontal for a single boolean. A label stacked over a tiny box looks like a heading that lost its section. The label is the choice itself, so normal weight is enough, and a checked default should be the common case rather than a quiet opt-in.

Radio

Monthly or yearly, under a legend that reads Subscription plan. The set is the question, and each option is its own horizontal field so the hit target includes the word. FieldLegend with variant set to label is quieter than the address legend, which fits a short choice. Only one plan can be on, and a checkbox list would lie about that.

Switch

Multi-factor authentication puts the label on one side and the switch on the other. Horizontal orientation matches a settings row. A switch stacked under a bold label looks like a field that forgot its input. There is no description, so if enabling it has a consequence, keep that sentence with the label and the row height stays even.

Choice Card

The whole plan row chooses the radio, not a 16 pixel circle. Wrap Field in FieldLabel, use FieldTitle for Monthly or Yearly, and put the radio at the end. FieldTitle is the visual name when another label nested inside the wrapping label would confuse the association. Save this for a handful of cards, because a long list is just a radio group with extra chrome.

Group

Email, a rule, then name. FieldGroup stacks them and FieldSeparator is only a pause between unrelated questions, so there is no shared legend. Use the rule when the stack would otherwise read as one blob. Skip it when a fieldset legend already says why the inputs belong together, and give the separator a short word such as or only when the pause itself needs a label.

Rtl

The public-name field in Arabic: caption, input, and the sentence about the display name, with dir set to rtl on the wrapper. Alignment follows that direction, which is the check before a translated form ships. A physical left margin on the label lands on the wrong side, and this is where it shows. The placeholder may stay in another language, but the caption should not.

Responsive

The label and the hint stay a pair, and the input moves beside them once the container is wide. orientation set to responsive only switches inside a FieldGroup, because the breakpoint is a container query on the group, not the viewport. FieldContent holds the caption and the description so a horizontal field can line that pair up with the control. Narrow, it stacks, which is what a card column wants.

FAQ

API Reference