Skip to content

Field

C-09 · Components · Inputs

All elements · Field on the Components page

Last checked 2026-10-22 · Awaiting approval · Accessibility tests

Copies the bun run a11y:approve command for Field.

Field

C-09WCAG 2.2 AA · Passed #402

The control shell: label, helper/error text, adornments, sizing. Every input-like component (TextField, Select, DatePicker, InputFieldMapper) is a Field around a Control.

Axis Values
data-size md 44px (default) · sm 32px
data-label-placement top (default) · start
data-required · data-disabled · data-readonly · data-invalid / aria-invalid state
data-mode click-to-edit (rest state looks like text)
__label · __control · __adornment · __helper · __counter slots
States
Helper text below the control.
Enter a valid email address.

Guidance

When to use

  • Use a field as the shell for every input-like control: text fields, selects, date pickers and the mapper.
  • Use it to give a control its label, helper text, error text, counter and adornments in one consistent layout.
  • Use data-label-placement="start" in dense property forms where labels line up in a column.
  • Use data-mode="click-to-edit" for values shown as text on a record that the user can edit in place.

When to consider something else

  • If you need a free-text input, use a text field, which is a field around a typed control. See TextField.
  • If you are laying out a full form with sections and actions, use the form composite. See Form.
  • If the value is read-only and never edited, show it as plain text in the object view instead. See ObjectDisplay.

Usability

Do
  • Always show a visible label; placeholder text is not a label.
  • Put format hints in helper text, not only in the placeholder.
  • Replace helper text with a specific error that says how to fix it.
  • Mark required fields consistently, and say in the form intro what the asterisk means.
  • Use data-readonly for values the user can read and copy but not change.
Don’t
  • Don't use data-disabled to show values the user should still be able to read and copy.
  • Don't validate on every keystroke; validate on blur or submit.
  • Don't use click-to-edit for fields that must be filled in a new record.

Accessibility

Keyboard

Field keyboard
Keys Action
Tab Moves focus to the control, then to any adornment button such as Clear.
Shift+Tab Moves focus to the previous control.

Roles and names

  • .qf-field__label is a <label for> that points at the control's id.
  • Helper, error and counter text are linked with aria-describedby on the control.
  • Invalid fields set aria-invalid="true" on the control as well as data-invalid on the field.
  • data-required only draws the asterisk; the binding must also set required or aria-required="true" on the control.
  • Use native disabled and readonly on the control; adornment icons are aria-hidden, adornment buttons need aria-label.

Focus

  • Focus shows on the whole control shell (:focus-within), with a red ring when invalid.
  • A click-to-edit field is a real input at rest; it must stay in the tab order and show the same focus ring.

Other requirements

  • Errors must be described in text (3.3.1) with a suggestion (3.3.3), not only by the red border (1.4.1).
  • The a11y report lists the invalid helper text as classic-theme contrast debt (1.4.3).
  • Control borders must reach 3:1 against the surface (1.4.11); the read-only dashed border helps tell it apart from disabled.
  • md is 44px and sm 32px high, both above the 24px minimum (2.5.8).
  • On submit with errors, move focus to the first invalid field or an error summary.

Test your implementation too. This guidance covers the element as specified here. How a screen composes it (labels, order, announcements) still needs its own keyboard and screen reader check.

Accessibility tests

WCAG 2.2 AA · Passed

Passed the gate (run 358b316 on 2026-10-22): no finding in any theme. Awaiting a person’s approval of the checklist below.

Field test checklist
Area Automated A person checks
General Passed Color is never the only cue, text alternatives say the same thing as the graphic, and the element reads the same in the light and the dark theme.
Zoom Passed At 200% zoom, at 320 CSS pixels wide and with the WCAG text-spacing overrides, nothing is lost, clipped or overlapping.
Keyboard Passed Every row of the Keyboard table works, focus is always visible and never trapped, and the tab order follows the reading order. (2 rows)
Screen reader Passed With NVDA or JAWS on Windows and VoiceOver on macOS, names, roles and states are announced as Roles and names says, and changes are announced once. (5 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- field --by "Your name" and commit a11y/approvals.json with the rebuilt pages. All test status

Package

Consumers link one stylesheet, css/classic/index.css, which includes every element. The files below are where this element is defined.

Field package
Source css/classic/components/inputs.css
Specimens also use Box · Button · Card · Chip · Control · Icon · Table · Text · Toolbar
Sprites sprites/icons.svg
React Not yet available: the React binding has not started.

Latest updates

No recorded changes yet.

All release notes