Skip to content

Control

P-13 · Primitives · Primitives

All elements · Control on the Primitives page

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

Copies the bun run a11y:approve command for Control.

Control

P-13WCAG 2.2 AA · Passed #440

The bare focusable form element with no chrome. Field (C-09) supplies the label, border and helper shell; Control is the <input>, <textarea> or <select> inside it. Shown here without a Field to make the point.

Axis Values
type · placeholder · inputmode · autocomplete native attributes pass through
data-align · data-mono end (numeric) / monospace
:disabled · [readonly] native state
Bare controls (no Field)

Guidance

When to use

  • Provide the actual <input>, <textarea> or <select> inside a Field or another component that draws the chrome.
  • Build a cell editor in a data grid or spreadsheet where the cell supplies the border.
  • Show numbers aligned to the end with data-align="end" and data-mono.
  • Pass native attributes such as type, inputmode and autocomplete straight through.

When to consider something else

  • When the user needs a labeled form input with helper and error text, use TextField or Field. See TextField.
  • When the user picks from a set of options, use Select, which handles listbox behavior. See Select.
  • When the value is a date, use DatePicker. See DatePicker.
  • When the value is a number stepped up and down, use SpinButton. See SpinButton.

Usability

Do
  • Set autocomplete on fields about the user, such as name and email (1.3.5).
  • Use inputmode to bring up the right on-screen keyboard for numbers.
  • Use readonly for values users can read and copy but not change, and :disabled only for values that do not apply.
  • Keep the placeholder as an example, not the label.
Don’t
  • Don't ship a bare Control with no visible label; it is shown alone in the catalog only to make a point.
  • Don't remove the focus indicator unless a wrapper such as Field draws one.
  • Don't use data-mono for prose.

Accessibility

Keyboard

Control keyboard
Keys Action
Tab Moves focus to the control; Shift+Tab moves back.
Typing, Arrow keys, Home, End Native text editing and caret movement.
Arrow Up / Arrow Down In a native <select>, changes the option (browser default).

Roles and names

  • Native elements give the role and state: textbox, combobox or listbox, :disabled, readonly, required.
  • Every control needs an accessible name: a <label for> (Field provides it) or aria-label, as the bare specimens use.
  • Errors use aria-invalid="true" and aria-describedby pointing at the message; Field wires these.

Focus

  • Inside .qf-field__control the Control's own focus style is removed and the Field draws the focus ring (2.4.7).
  • Outside a Field, the global :focus-visible ring applies; a host that removes it must draw its own.

Other requirements

  • Text needs 4.5:1 (1.4.3); placeholder and readonly text use lighter inks, so check them in both themes.
  • The control's boundary comes from its wrapper and needs 3:1 against the background (1.4.11).
  • Target size comes from the wrapper's height; keep it at least 24 by 24 CSS px (2.5.8).
  • Do not trigger navigation or submit on input or focus alone (3.2.1, 3.2.2).

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.

Control 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. (3 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. (3 items)

Approving. When the checklist passes on the checked run, record it with bun run a11y:approve -- control --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.

Control package
Source css/classic/primitives/behavior.css
Specimens also use Box · Card · Chip · 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