TextField
TextField allows for multiple types of text input.
also known as Text Input
Props
Usage guidelines
- Any time succinct data needs to be entered by a user, like a date, email address, name, or Pin title.
- Situations where long amounts of text need to be entered, since the full content of the TextField will be truncated. Use TextArea instead.
Best practices
Use helper text for important information. Helper text helps users understand how to complete the text field or to indicate any needed input.
Put essential information in the placeholder text, since it disappears when the user types. The placeholder text is not a replacement for the label.
Always ensure the text field has a visible label. The label provides context and supports users when filling in information.
Remove the label, as this creates accessibility and usability issues.
Only place related fields on the same line.
Place unrelated text fields on the same line, as this can create comprehension issues.
Provide clear and useful error messages that help the user fix the issue. Error messages should be displayed in a timely manner — typically once the field loses focus or when the form is submitted.
Display generic error messages, such as "There is an error".
Consider all text fields as required, unless explicitly noted as optional.
Mark fields as required.
Accessibility
Comprehension
Be sure to provide instructions to help users understand how to complete the form and use individual form controls.
Labels
TextField comes with Label built-in: just use the label
prop. We strongly encourage always supplying a label. Be sure to provide a unique id
so the Label is associated with the correct TextField.
If TextField is labeled by content elsewhere on the page, or a more complex label is needed, the labelDisplay
prop can be used to visually hide the label. In this case, it is still available to screen reader users, but will not appear visually on the screen.
Validation
When providing a validation message, make sure the instructions are clear and help users complete the field. For example, "Passwords must contain at least 20 characters". In addition, use the helper text to provide instructions to help users understand how to complete the text field or to indicate any needed input, allowed formats, timing limitations, or other pertinent information.
These practices give users of assistive technologies more information about the form, helping them to fill it out.
TextField has conventional keyboard support.
- Users relying on the keyboard expect to move focus to each TextField by using the tab key or shift+tab when moving backwards.
- Setting
disabled
will prevent TextField from receiving keyboard focus or input.
Autofocus
TextField intentionally lacks support for autofocus. Generally speaking, autofocus interrupts normal page flow for screen readers making it an anti-pattern for accessibility.
onSubmit
TextField is commonly used as an input in forms alongside submit buttons. In these cases, users expect that pressing Enter or Return with the input focused will submit the form.
Out of the box, TextField doesn't expose an onSubmit
handler or individual key event handlers due to the complexities of handling these properly. Instead, developers are encouraged to wrap TextField in a <form>
with an onSubmit
handler..
Localization
Be sure to localize errorMessage
, helperText
, label
, maxLength
's errorAccessibilityLabel
and placeholder
.
Variants
Helper text
Whenever you want to provide more information about a form field, you should use helperText
.
Label visibility
In some cases, the label for a TextField is represented in a different way visually, as demonstrated below. In these instances, you can set labelDisplay="hidden"
to ensure TextField is properly labeled for screen readers while using a different element to represent the label visually.
Read-only
Read-only TextFields are used to present information to the user without allowing them to edit the content. Typically they are used to show content or information that the user does not have permission or access to edit.
Password
Disabled
disabled
TextFields cannot be interacted with using the mouse or keyboard. They also do not need to meet contrast requirements, so do not use them to present info to the user (use readOnly
instead).
Error message
TextField can display an error message. Simply pass in an errorMessage
when there is an error present and TextField will handle the rest.
Don't use errorMessage
to provide feedback on character count errors. See the maximum length variant for more details.
Tags
You can include Tag elements in the input using the tags
prop.
Note that TextField does not internally manage tags. Tag management should be handled in the application state through the component's event callbacks. We recommend creating new tags on enter key presses, and removing them on backspaces when the cursor is in the beginning of the field. We also recommend filtering out empty tags.
This example showcases the recommended behavior. In addition, it creates new tags by splitting the input on spaces, commas, and semicolons.
EnterKeyHint
The enterKeyHint
prop presents to the user a more accurate action label for the enter key on virtual keyboards. These are the values for each use case:
- "enter": inserting a new line
- "done": there is nothing more to input and the input editor will be closed
- "go": taking the user to the target of the text they typed
- "next": taking the user to the next field that will accept text
- "previous": taking the user to the previous field that will accept text
- "search": taking the user to the results of searching for the text they have typed
- "send": delivering the text to its target
Maximum length
Textfield supports the native maxlength input attribute. maxLength
sets the maximum number of characters allowed to be entered by the user in Textfield. maxLength
must be an integer value 0 or higher.
The user cannot exceed the maximum number of characters interacting with the component. Whenever possible, avoid setting initial values from the parent component's state that already exceed the maxLength
.
When maxLength
is passed to TextField, the component displays a character counter as well as a warning or problem Status when the user reaches or the prepopulated controlled value exceeds the maximum length of characters.
The first example shows an empty Textfield with maxLength
set to 20 characters. The second example shows the warning and problem Status.
Refs
TextField can accept a ref for anchoring Popover-based components.
Component quality checklist
Quality item | Status | Status description |
---|---|---|
Figma Library | Ready | Component is available in Figma across all platforms. |
Responsive Web | Ready | Component is available in code for web and mobile web. |
iOS | Component is not currently available in code for iOS. | |
Android | Planned | Component is slotted to be built for Android. |
Related
TextArea
When users need to enter long amounts of text, use TextArea to ensure the full content will be shown.
NumberField
For numerical input, use NumberField. Exceptions: for telephone numbers, use <TextField type="tel" />
. And for numerical input with possible leading 0's (e.g. ZIP codes), use <TextField type="text" />
.
SearchField
If the input is used for searching content, use SearchField.