Skip to content

TextField

C-10 · Components · Inputs

All elements · TextField on the Components page

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

Copies the bun run a11y:approve command for TextField.

TextField

C-10WCAG 2.2 AA · Passed #403

All twelve free-text variants are a type on the Control plus an optional adornment. Nothing else changes.

Axis Values
type text · email · password · search · tel · url · number · currency · percent · textarea · masked · code
Variants
£
%
Optional.0 / 500

Guidance

When to use

  • Use a text field for free-text values that are not from a fixed list, such as names, references and notes.
  • Use the matching type so browsers and assistive tech get the right keyboard and checks: email, tel, url, number, password, search.
  • Use the currency or percent variants with an adornment for money and rates, aligned to the end with data-align="end".
  • Use the textarea variant with a counter for longer text with a limit.
  • Use the masked or code variants (data-mono) for fixed formats, such as sort codes or IDs.

When to consider something else

  • If the value comes from a known list, use a select or combobox. See Select.
  • If the value is a date or time, use a date picker. See DatePicker.
  • If the number is stepped in small units with a unit suffix, use a spin button. See SpinButton.
  • If the text needs formatting, use the editor. See Editor.

Usability

Do
  • Size the field to the expected length of the value.
  • Show the expected format in helper text, such as "00-00-00", not only in the placeholder.
  • Set autocomplete on fields about the user, such as email and tel.
  • Accept common input variations (spaces, dashes, currency symbols) and normalize them.
Don’t
  • Don't use type="number" for IDs, phone numbers or codes; use text with inputmode.
  • Don't block paste in any field, including passwords.
  • Don't rely on the adornment alone to say the unit or currency.

Accessibility

Keyboard

TextField keyboard
Keys Action
Tab Moves focus into the field, then to an adornment button such as Show password.
Arrow Up or Arrow Down On type="number", steps the value (native behavior).
Enter In a single-line field inside a form, submits the form; in a textarea, adds a new line.

Roles and names

  • The control is a native <input> or <textarea> with a <label>; all field rules apply.
  • The currency symbol or percent adornment is not part of the name; include the unit in the label or link it with aria-describedby.
  • The Show password button should be a toggle with aria-pressed and a stable name, such as "Show password".
  • The counter is linked with aria-describedby; do not make it a live region that speaks on every keystroke.

Focus

  • Focus shows on the field shell; the caret stays in the input.
  • Showing or hiding the password must keep focus on the toggle button.

Other requirements

  • 1.3.5 Identify Input Purpose: set the autocomplete token on personal-data fields.
  • Placeholder text must reach 4.5:1 if it carries information (1.4.3); better, keep it to examples.
  • When the user nears the character limit, announce it once politely (4.1.3).
  • The field must reflow at 320 CSS px (1.4.10) and text must survive 200% zoom and text spacing changes (1.4.4, 1.4.12).

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.

TextField 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. (4 items)

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

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