Overview
Text inputs allow users to enter free-form text data. Their single-line format is ideal for short entries. They have a fixed height and support free-form entries with letters, numbers, or symbols. Their widths can be fixed to match the expected size of the input data or set to flexibly adjust to the container.
When to use
- Use a text input when the expected user input is a single line of text.
- Use a text input when a user needs to enter unique information that cannot be predetermined with a preset list of options.
- Opt for a text input when users need to input memorable data that is quicker to enter in a free-form format rather than through a more complex control.
When not to use
- If users can only select from a predefined list, avoid using a free-form text input, as it may lead to errors. Instead, use a selection control like a dropdown, select, or response buttons.
- Label text: Text that guides users on the required input for the field. It is mandatory unless an approved accessibility exemption applies.
- Value: The data or text input provided by the user in the field.
- Placeholder: Temporary text that provides a hint or example of the expected input.
- Input field: The input field is the container where users enter data and must meet a 3:1 non-text contrast ratio for accessibility.
- Icon: Used to indicate required data or provide validation feedback.
- Assistive text (optional): Additional text that offers support or context to the input label.
- Helper text (optional): Text that offers additional guidance or context for the input field, often explaining the required data format.
- Input action button: Offers interactive functionality like password visibility toggling or a date picker.
Size
Text inputs come in two sizes: small and medium. These options provide flexibility in layout design, but field heights should remain consistent when grouping form components on the same page.
|
Size
|
Height (px/rem)
|
Use case
|
|---|---|---|
| Small | 32 / 2 | Use when space is limited |
| Medium | 44 / 2.75 | This is the standard size and the most frequently used. If unsure, opt for the medium size |
Small input pending
Labels
Clear labelling helps users understand what information to enter in a text input. Text fields should always have a label.
- Use sentence-style capitalisation for all labels, except for product names and proper nouns.
- Keep labels short and concise.
- Do not use colons after label names.
Placeholder text
Optional placeholder text offers hints or examples of what to enter but disappears once the user starts typing. It should not replace a persistent label or include essential information.
- Use sentence-style capitalisation and, in most cases, write the text as a direct statement without punctuation.
- Placeholder text is not required and is not shown by default in text input fields.
- Placeholder text can hinder user interactions and should only be included when necessary.
Assistive / helper text
Optional assistive and helper text provides relevant information to assist users in accurately completing a field and is often used to clarify the required data format.
Assistive text sits directly below the input label and offers support or context to the input label, whereas the helper text offers additional guidance or context for the input field, often explaining the required data format.
- Use sentence-style capitalisation, and in most cases, write the text as full sentences with punctuation.
- When used, helper text appears persistently beneath the field, except when replaced by an error message.
Overflow content
If a user’s input exceeds the single-line limit of a text field, the content can horizontally scroll within the field container as the cursor moves.
To prevent a user’s input from exceeding the single-line limit of a text field, set an appropriate width to the field that matches the expected data size or use an alternative component like a text area.
States
Text inputs have multiple interactive states: resting, focus, error, disabled, and read-only. For more details on these interactive states, refer to the style tab.
|
State
|
When to use
|
|---|---|
| Resting | The resting state refers to when a text input is live, but the user is not directly interacting with it. This is commonly known as the default or normal state of the component, and it can contain no content, placeholder text, or user-generated content. |
| Focus | When a user tabs to or clicks on the text input, it enters the focused state, signalling that the user has successfully navigated to the component. |
| Active | When a user is actively typing content into the field. |
| Error | When the user input is invalid or a required text input has not been filled in, or due to a system error. This state requires user intervention before data can be submitted or saved. |
| Disabled | When the user cannot interact with a component and all interactive functions have been disabled. Unlike read-only states, disabled states are not focusable, are not read by screen readers, and do not need to meet visual contrast requirements, making them inaccessible if interpretation is necessary. |
| Read-only | When the user can review but not modify the component. This state disables all interactive functions, similar to the disabled state, but it remains focusable, accessible by screen readers, and meets visual contrast requirements for readability. |
Assistive / helper text in disabled and read-only states
Text inputs in disabled and read-only states do not require assistive / helper text because users cannot modify their content, eliminating the need for guidance on data entry. In these states, any necessary context should be provided through labels or surrounding content rather than additional helper text that might imply interactivity.
Validation
Text input data should be validated upon form submission. For comprehensive guidance on errors and validation, refer to the form pattern.
Validation messages take precedence over helper text and will replace it when triggered. If an input displays helper text, it will be hidden in favour of the validation message when an error state occurs.
Error
An error state is triggered when invalid data is entered or a required field is left empty. It is visually indicated by a red border, an error icon, and an error message to help users identify and correct the issue.
Required vs optional
Text inputs can be marked as optional or required based on the context. For detailed guidance on requirement labelling, refer to the form pattern.
If most fields are optional, label only the required fields with “(required)”.
If most fields are required, label only the optional fields with “(optional)”.
Mouse
Users can activate a text input by clicking on the field container. A separate click is needed for additional actions like an input action button.
Keyboard
|
Key
|
Interaction
|
|---|---|
| Tab | Brings focus to the text input. |
| Enter or space | Activates any associated actions added to the input, such as an input action button. |
| Esc | Closes any associated actions added to the input. |
| ctrl or opt + left/right arrows | Moves you word by word inside the field. |
| ctrl or opt + up/down arrows | Moves the cursor to the start or end of the input content. |
Inputs with icons
Icons in text inputs can provide helpful visual cues. They should always serve a clear purpose and support the user’s task, not distract from it. Icons must be intuitive and consistently styled to ensure clarity for users.
- Icons should always appear on the left of the input
- Icons used in inputs should be directly related to the intended value entered by the user.
- Icons cannot be used in conjunction with input action buttons
Input action buttons
Input action buttons allow users to activate additional actions associated with the text input, such as toggling password visibility or triggering a date picker. No more than one action button can be used inside an input at anytime. Input action buttons must not be used in conjunction with icons to maintain clarity for the user.
Password input
Password input is a variant of the text input field used to collect sensitive data by hiding the characters as they are typed. Users can toggle visibility by clicking the view icon on the right of the input field. When using password input, ensure that helper text clearly outlines any data format requirements, such as allowed character types or structure.
Clear button
The clear button allows users to remove the content from a text input by clicking it. By default, the clear button is hidden until the user enters data, and it only appears when the user hovers over the input. This approach helps to reduce visual clutter, especially in situations with multiple inputs on a screen.
Clear buttons cannot be used in conjunction with input action buttons.