组件 · 输入

Field

The label, help text and error around a form control, wired to it for assistive technology.

稳定

import { Field } from "@botiverse/raft-ui";

本页尚未翻译

译文完成之前，这里显示英文原文。阅读英文版

A field puts a label above a form control and help text below it, and replaces the help text with an error when the value is invalid. Every input, textarea and select in a form sits in a field.

field/compositions/preview

When to use

Situation	Use
A labeled control in a form: an input, a textarea, a select	Field
A checkbox, radio or switch with its label beside it	Field with `FieldItem`
A setting row with a switch	A settings row (ListRow) with a Switch
A section of a large form, with a heading and a description	FormSection

Anatomy

Field: the column that holds the parts. Required.
FieldLabel: the label, above the control. Required unless the control has its own accessible name.
The control: Input, InputGroup, Textarea, Select or FieldControl for another native control.
FieldDescription: help text below the control. Optional.
FieldError: the error, in place of the help text. Shown only while the field is invalid.
FieldItem: a row that puts a checkbox, radio or switch beside its label and description, 8px apart. It centres the control on the label's first line by moving it, so the row keeps its height: a switch overhangs the label's line rather than making the row taller. It works from its own line height, so give it the same size as the label: <FieldItem size="sm"> with <FieldLabel size="sm">. A mismatch leaves the control 1px off (Alignment).
FieldValidity: read access to the field's validity state, for custom messages.

Variants

Variant	Use for
`FieldLabel` default	Form fields
`FieldLabel size="sm"`	Dense layouts where the default label is too large for the space

field/compositions/compact-label

States

field/compositions/error

Invalid: set invalid on Field and data-invalid on the control. The control's border turns danger-strong, and FieldError takes the place of FieldDescription, in danger-strong. When to check and how the message reads are in Forms.
Disabled: disabled on Field turns the label, help text and error foreground-disabled.

Content

Where the label and help text go is in Forms.

Keep the label visible at all times. Don't use a floating label or a placeholder in its place.
Write the label in sentence case: Agent name.
Mark an optional field with optional, which adds "(optional)". Don't mark required fields: marking the optional ones is enough.
Make the help text one line about what the value is for: Shown in chat and on tasks.
Make the error say how to fix the value, with a correct example: Use lowercase and dashes: launch-week (Writing).
A label, help text or error of any length wraps, and breaks inside a word that is wider than the line, so it never pushes the field, a dialog or the screen wider. FieldItem lets its label column shrink for the same reason (Forms).

Accessibility

Field wraps Base UI Field. It connects the label, the description and the error to a Base UI control (Input, Select, Checkbox, Switch, RadioGroup) and passes the field's invalid and disabled state to it.

Give FieldLabel an htmlFor that matches the control's id when the control is not a Base UI one, such as Textarea, and point aria-describedby at the description.
FieldError has role="alert", so the error is announced when it appears.