Actions & Inputs
Text Field
Text Fields allow users to enter and edit text content into a UI. They typically appear in forms.
Status
Supported
Introduced
v3.13.0
Status
Supported
Introduced
v3.13.0
Anatomy
Text Fields contain four required elements and two optional elements.
| Item | Name | Description | Component | Optional |
|---|
Options
The Text Field has options that can be used to provide an appropriate experience for different use cases.
Size
There are three sizes of Text Field; small, medium, and large. The label, input container, placeholder/input text, start and end enhancers, and assistive text change size. Text Inputs match the same height as the Button, to align when used together.
Width
The width of a Text Field can be customised appropriately for its context, using full-width or a fixed-width value.
Placeholder text
The short hint is displayed in the input container before the user enters a value.
Note
Placeholder text is not accessible; use assistive text when providing instructions on completing a Text Field for clarity.
Start enhancer
The Text Field supports start enhancer property that allows for a component to be added to the start or end of the input container, for example, an icon.
End enhancer
The Text Field supports end enhancer property that allows for a component to be added to the start or end of the input container, for example, a Button.
Autocomplete
The Text Field supports native HTML autocomplete functionality that provides a visual hint to users if enabled. For more information, please refer to the HTML autocomplete attribute.
Max length
The Text Field supports native HTML max length value functionality that sets a maximum length of the number of characters entered. For more information, please refer to the HTML input attribute types.
Min length
The Text Field supports native HTML max length value functionality that sets a minimum length of the number of characters entered. For more information, please refer to the HTML input attribute types.
Pattern
The Text Field supports native HTML regex pattern functionality that the value of the input must match to be valid.For more information, please refer to the HTML input attribute types.
Type
The Text Field supports type functionality that sets the type of text field to render to the user. The types supported include 'text' (default for the Text Field component), 'email', 'password', 'tel', and 'number'.For more information, please refer to the HTML input types.
Input mode
The Text Field supports input mode functionality that hints at the type of data that might be entered by the user while editing the element or its contents. The input modes supported include 'text', 'email', 'tel', and 'numeric'.For more information, please refer to the HTML inputmode attribute types.
Handling multiple Text Fields
Selection controls (inputs), such as the Form Input TextField, can be grouped together with other selection controls, Labels, and Assistive Text together in a Fieldset. The Fieldset has a caption that gives a title attributed to the elements that appear in the Fieldset, called a Legend.
The Fieldset can also support other selection controls (inputs) such as the FormInput Radio, FormInput Switch, and FormInput Checkbox.
For more information, please refer to the Fieldset component.
Size
There are three sizes of Text Field; small, medium, and large. The label, input container, placeholder/input text, start and end enhancers, and assistive text change size. Text Inputs match the same height as the Button, to align when used together.
Width
The width of a Text Field can be customised appropriately for its context, using full-width or a fixed-width value.
Placeholder text
The short hint is displayed in the input container before the user enters a value.
Note
Placeholder text is not accessible; use assistive text when providing instructions on completing a Text Field for clarity.
Start enhancer
The Text Field supports start enhancer property that allows for a component to be added to the start or end of the input container, for example, an icon.
End enhancer
The Text Field supports end enhancer property that allows for a component to be added to the start or end of the input container, for example, a Button.
Autocomplete
The Text Field supports native HTML autocomplete functionality that provides a visual hint to users if enabled. For more information, please refer to the HTML autocomplete attribute.
Max length
The Text Field supports native HTML max length value functionality that sets a maximum length of the number of characters entered. For more information, please refer to the HTML input attribute types.
Min length
The Text Field supports native HTML max length value functionality that sets a minimum length of the number of characters entered. For more information, please refer to the HTML input attribute types.
Pattern
The Text Field supports native HTML regex pattern functionality that the value of the input must match to be valid.For more information, please refer to the HTML input attribute types.
Type
The Text Field supports type functionality that sets the type of text field to render to the user. The types supported include 'text' (default for the Text Field component), 'email', 'password', 'tel', and 'number'.For more information, please refer to the HTML input types.
Input mode
The Text Field supports input mode functionality that hints at the type of data that might be entered by the user while editing the element or its contents. The input modes supported include 'text', 'email', 'tel', and 'numeric'.For more information, please refer to the HTML inputmode attribute types.
Handling multiple Text Fields
Selection controls (inputs), such as the Form Input TextField, can be grouped together with other selection controls, Labels, and Assistive Text together in a Fieldset. The Fieldset has a caption that gives a title attributed to the elements that appear in the Fieldset, called a Legend.
The Fieldset can also support other selection controls (inputs) such as the FormInput Radio, FormInput Switch, and FormInput Checkbox.
For more information, please refer to the Fieldset component.
States
The Text Field has the following states. They can be displayed with both placeholder content or user-inputted content:
Base
Text Fields have a base state. This is the base style of the input before it has been interacted with by a user.
Hover
Text Fields have a hover state. The style of the input changes to visually communicate and provide feedback to the user that the Text Field is an interactive element.
Active
Text Fields have an active state. The style of the input changes to visually communicate and provide feedback to the user that the Text Field has been interacted with.
Selected (Focus)
Text Fields have a selected state. The style of the input changes and a caret element in the input is also visible to visually communicate and provide feedback to the user that the Text Field has been selected and they can input content.
Valid
Text Fields in a valid state change style and can display a valid icon when the inputted entry conforms to a specific format (e.g., email address, credit card number, password creation requirements, etc.).
The input style change and validation icon can appear as soon as a user types a valid entry in the input or on submit.
The Form component is used to define this validation behaviour.
Valid focus
Text Fields in a valid focus state changes style when the inputted entry conforms to a specific condition or format, while focused.
Valid hover
Text Fields in a valid hover state changes style when the inputted entry conforms to a specific condition or format, while hovering.
Invalid
Text Fields in an invalid state change style and can display an invalid icon when the inputted entry doesn’t conform to a specific format (e.g., email address, credit card number, password creation requirements, etc.).
The input style change and validation icon can appear as soon as a user types a valid entry in the input or on submit.
The Form component is used to define this validation behaviour.
Invalid focus
Text Fields in an invalid focus state changes style when the inputted entry doesn’t conform to a specific condition or format, while focused.
Invalid hover
Text Fields in an invalid hover state changes style when the inputted entry doesn’t conform to a specific condition or format, while hovering.
Disabled
Text Fields in a disabled state show that an input exists, but is not available to the user in that scenario. When a user’s cursor hovers over a Text Fields in a disabled state the cursor shows as not-allowed.
Disabled Text Fields are often used to maintain layout consistency and communicate that an input may become available if another condition has been met, e.g.selected a previous option in a form.
Content and data in a disabled Text Field can not be submitted in a form.
Read-only
Text Fields in a read-only state communicate to the user that an input exists, but cannot be modified in that scenario (however, a user can tab to it, highlight it, and copy the text from it).
Read-only Text Fields are often used to maintain layout consistency and communicate that an input may become available if another condition has been met, e.g. selected a previous option in a form.
Content and data in a read-only Text Field can be submitted in a form.
Behaviours
The following guidance describes how the Text Field component behaves.
Input Text Overflow Truncationn
When the Text Field text is too long for the available horizontal space, the text truncates when text is inputted.
Truncation is visually indicated using text-overflow: elipsis via the style presets.
Validation
The Text Field validation rules can be defined for onSubmit or onBlur, for both the initial validation and re-validation using the Form.
For more information, please refer to the Form component.
Note
Validation only works if the FormInput TextField uses the Form component.
Validation icon
An icon is used to indicate if the select is in a valid or invalid state. Validation is set on the Form component.
Input Text Overflow Truncationn
When the Text Field text is too long for the available horizontal space, the text truncates when text is inputted.
Truncation is visually indicated using text-overflow: elipsis via the style presets.
Validation
The Text Field validation rules can be defined for onSubmit or onBlur, for both the initial validation and re-validation using the Form.
For more information, please refer to the Form component.
Note
Validation only works if the FormInput TextField uses the Form component.
Validation icon
An icon is used to indicate if the select is in a valid or invalid state. Validation is set on the Form component.
Usage
The following guidance describes how and when to appropriately use a Select component.
Do
The width of the Text Field should be proportional to the expected user input. For example, when capturing date of birth, the format should be split up into day/month/year i.e DD - MM - YYYY using multiple Text Fields, as this allows users to focus on inputting a specific value, reducing cognitive load. Using identical input widths for all Text Inputs in your forms will make them visually pleasing, but will be harder for a user to complete.
Avoid using the Text Field if you need to let users enter longer answers that might span multiple lines. Consider using an alternative, such as Textarea.
Don’t
Avoid using Text Fields to capture multiple pieces of information from users, as this increases cognitive load. Instead, consider using multiple text fields in these cases.
Do
Input labels and placeholder text should be in sentence case. This helps with scannability and legibility.
Don’t
Input label text shouldn't be truncated or wrap over two or more lines. Keep it short, clear, and fully visible.
Do
Use an appropriate input type for the data you collect. Providing the right type of input field for requested data will help users enter information in the right format and avoid mistakes, making the process as easy and efficient as possible. e.g. use a Password Input Field for users to input their password.
Don’t
Use an appropriate input type for the data you collect. Providing the right type of input field for requested data will help users enter information in the right format and avoid mistakes, making the process as easy and efficient as possible. e.g. use a Password Input Field for users to input their password.
Do
Swap Assistive Text with error text if the Text Field is invalid. Once the input is valid then the assistive is then shown again.
Don’t
Avoid prematurely validating the input e.g. avoid setting the input to invalid before the user has finished typing.
Do
Where possible, use onBlur validation (when the user clicks out the input, the input is validated). When the user’s inputs are checked as the user progresses through the form, as opposed to checking all the inputs in one process on submitting the form. This way is an improved user experience and guides the user through the form completion.
Do
Write error text that communicates a solution. Error text should be written in no more than a few clear, concise and complete sentences.
Do
Write error messaging in a human-centered way by guiding a user and communicating a solution. For example, if a user didn’t complete a required Text Field that asks for their date of birth, write the error text like you’re offering a hint to help them to understand what needs to go in the missing Text Input e.g: “Enter your date of birth.”
Accessibility Considerations
The Text Field has the following accessibility considerations:
| Order | Element | Role |
|---|
| Command | Description |
|---|
| Element | Attribute | Value | Description | User Supplied |
|---|
API
The Text Field has a range of props that can be used to define an appropriate experience for different use cases.
There are two components exported from the package, one for use within the NewsKit Form component, and one for use as a controlled component.
The FormInput TextField has a range of props that can be used to define an appropriate experience for different use cases. Use this component within the NewsKit Form component.
| Name | Type | Default | Description | Required |
|---|
The name & rules props are set on the form input level. If you want to add validation rules or set the name of this component, please refer to the Form component.
The NewsKit FormInput TextField supports different native HTML attributes, eg. defining the input type as password, or email etc.
Engineer to check the validation related props at the time of implementation.
The TextField has a range of props that can be used to define an appropriate experience for different use cases. Use this component as a controlled component, for instance where you have a custom validation mechanism.
| Name | Type | Default | Description | Required |
|---|
The NewsKit Text Field supports different native HTML attributes, eg. defining the input type as password, or email etc.
Compliance
All of the components in the NewsKit design system go through a comprehensive set of checks to ensure that we are producing compliant and best practice components.
| Feature | Description | Status |
|---|