Field

When to useLink to "When to use"

• Around a text input, select or any custom control that needs a visible label.
• To show validation errors consistently.
• With group to label a set of controls such as a radio group.

Use something else when:

• the control brings its own label: Checkbox
• the component already includes a Field, such as TextField

UsageLink to "Usage"

import { Field, InputBase } from "@arshad-shah/cynosure";

<Field label="Email" description="We never share it." error={error} required>
  {(f) => <InputBase id={f.id} aria-describedby={f.describedBy} invalid={f.invalid} required />}
</Field>

The render prop gives you id, describedBy and invalid. Pass them to the control.

Errors and requiredLink to "Errors and required"

error is shown below the control, announced with role="alert", linked to the control and marks it invalid. required draws the marker as a shape, not a typed asterisk; also pass required to the control itself.

Settings rowsLink to "Settings rows"

layout="split" puts the label and description at the start and the control at the end of one row, centred on the text, as in a settings page. When the field is too narrow for both, the control moves under the text. width gives the control one of three widths (or the whole field), so a column of settings lines up whatever the labels. Labels, descriptions and errors stay linked to the control. Every control built on Field takes both props too (FieldLayoutProps): TextField, Select, Combobox, TagInput, PathField, NumberField, DateField, TimeField, ColorField, TextArea and HotkeyField.

<Field layout="split" width="md" label="Font" description="Used in the query editor.">
  {(f) => <InputBase id={f.id} aria-describedby={f.describedBy} />}
</Field>
<Select layout="split" width="md" label="Theme" description="Light, dark or the system's." options={themes} />

GroupsLink to "Groups"

With group, Field renders a fieldset and the label names the whole group instead of one control.

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Label: a label linked to the control, or the group label when group is set.
• Hidden label: labelHidden keeps the label for assistive tech but takes no space. Prefer visible labels.
• Description and error: linked through aria-describedby. The error also announces itself.
• Size: sm, md (default) or lg.
• Split layout: the order in the page stays label, description, control, then error, so screen readers and the Tab key meet them as in the stacked layout. Right-to-left text mirrors the row.

ThemingLink to "Theming"

Tokens: --cy-field-gap, --cy-field-label-weight, --cy-field-label-color, --cy-field-description-color, --cy-field-error-color and --cy-field-required-color. Control widths: --cy-field-control-width-sm, -md and -lg (160, 256 and 384px). The split layout keeps the text at least --cy-field-split-text-min (192px) wide before the control moves under it.

The field skin: --cy-field-control-border, --cy-field-control-bg and --cy-field-control-radius style the box of every field at once (TextField and the fields built on it, and HotkeyField), and --cy-field-control-sunken-bg the fill of a box that cannot be edited (a read-only TextField, a disabled HotkeyField). Each control's own tokens (--cy-text-field-bg…) still win over them.

createTheme({ components: { field: { gap: "8px", labelWeight: "600" } } });

className and style are for layout only.

RelatedLink to "Related"

TextField · Checkbox · Stack