TextInput

Role and semantics

TextInput renders a native <input> and binds the label to it with <label for>, so clicking the label focuses the input. Help text and error text are linked with aria-describedby, description first, then error. When there is an error, the input carries aria-invalid. required is set as the native attribute, which conveys the same information to screen readers as aria-required. The error message is not a live region: after a failed submit, moving focus to an error summary or the first invalid field is up to the team that builds the form.

Keyboard

Key	Behaviour
Tab	Focuses the field. A disabled field is skipped; a read-only field takes focus.
Shift + Tab	Goes back to the previous field.
Typing keys	Enter the value; the value does not change in a read-only or disabled field.
Click on the label	Focuses the input.

For numeric fields, inputMode="numeric" or "decimal" opens the right keyboard on mobile. Do not use type="number": it drops leading zeros and changes the value on mouse wheel.

Focus

On focus the box border turns to the focus colour and a 2 px ring is drawn 1 px inside the box. The ring does not spill outside the box, so a parent’s overflow setting does not clip it. The ring sits on the box that wraps the input and the start and end content, not on the input alone; a small action in the start or end content also makes the box look focused when it takes focus.

Screen reader output

Reading order: name (label), role, state, description. Examples (wording varies by screen reader):

• Required field: “IBAN required, edit text, required, Starts with TR.” The word “required” in the label is the visually hidden text next to the *; it comes from the ui.field.required string in the Provider language. The * itself is not read.
• Optional marking: with necessityIndicator="optional" the label reads “Note (optional)”; the text comes from the ui.field.optional string.
• Invalid field: “Postal code, edit text, invalid entry, Your 5-digit postal code. A postal code has 5 digits.” The description is read first, then the error.

Contrast

Values are computed from the light and dark modes of the bigbang and fixture brands (WCAG relative luminance formula). The field box sits on surface-raised and the page on surface-default; each row gives the lowest over both surfaces and both brands.

Element	Target	Light mode	Dark mode
Entered value (color-text-default)	4.5:1	16.16:1	15.44:1
Placeholder (color-text-placeholder)	4.5:1	4.63:1	6.41:1
Label (color-text-default)	4.5:1	16.16:1	15.44:1
Help text (color-text-subtle)	4.5:1	8.77:1	9.23:1
Error text (color-text-danger)	4.5:1	7.23:1	7.94:1
Input border (color-border-input)	3:1	4.63:1	3.49:1
Invalid border (color-border-danger)	3:1	5.45:1	5.53:1
Focus ring (color-focus-ring)	3:1	5.97:1	7.27:1

Text and borders of a disabled field are exempt from the WCAG contrast requirement and are not counted.

WCAG 2.2

Criterion	How TextInput meets it	What the product team must do
1.3.1 Info and relationships	The label is bound with <label for>, help and error with aria-describedby; the requirement is set with native required.	Group related fields (fieldset, legend).
1.3.5 Identify input purpose	autoComplete is passed to the input.	Give email, phone, name and address fields the right autoComplete value.
1.4.3 Contrast (minimum)	Value, label, help, error and placeholder text reach at least 4.5:1 in every brand and mode (table above).	Do not apply colours outside the tokens.
1.4.11 Non-text contrast	The input border and the focus ring reach at least 3:1.	Do not place the field box on a background that has no border.
2.4.6 Headings and labels	label is a required property; the label is visible.	Write a short label that says what the field asks for.
2.4.7 Focus visible	On focus the border changes and a 2 px ring is drawn.	Do not remove the focus ring with outline: none.
2.5.3 Label in name	The visible label starts the accessible name; “required” is only appended.	Do not override the label with a different aria-label.
3.3.1 Error identification	The error text is linked to the field and the input carries aria-invalid; it does not rely on colour alone.	Write the error text and run validation in the app.
3.3.2 Labels or instructions	label and description let you state the format up front.	State the expected format in the help text.
3.3.3 Error suggestion	The component shows the message but does not produce its content.	Make the error text say how to fix the problem.
4.1.2 Name, role, value	It uses a native <input>; name, role and value come from the browser; states use aria-invalid and native attributes.	Do not change the input’s role with render or role.