Anatomy
- Label: (Optional) Descriptive text that helps users understand what information to enter in to the field
- Prefix: (Optional) Icon positioned at the beginning of the text to provide visual clues and provide context to the user
- Input Text: The text that the user enters into the field
- Suffix: (Optional) Icon positioned at the end of the text to provide visual clues and provide context to the user
- Container: The bounding box that contains all of the color, text, icon, of the field
- Feedback: A hint or an error message.
Usage Guidelines
When to use this component
- Use a Text Input when a user needs to enter text — either a single line (e.g. a name, email address, or search query) or multiple lines using the multiline prop (e.g. a message or description).
- Use a Text Input when the user needs to enter an unknown value, rather than selecting from a predefined list.
- Use a Text Input when the data needs to be validated for a specific format, such as an email address or a phone number.
When not to use this component
- Don't use an input when a user needs to select from a small, fixed list of mutually exclusive options. Radio Buttons or a Select are a better choice.
-
Don't use an input for complex selections, like a date or a range of values. A specialized component is more user-friendly.
Best Practices
Use a single-line text field for short, concise input.
Don't use a single-line Text Input for longer content like messages or descriptions — use the multiline prop instead.
Use labels to specify the data required in the input field.
Do not omit labels — they are essential for input completion and accessibility.
Keep the label short and concise. Always use sentence case.
Avoid using long sentences or colons.
When using placeholders, write direct examples using sentence-case.
Do not use placeholders as labels or as hints or to provide important information.
Use feedback to provide useful information about the required input.
Do not duplicate information, if an error message is repeating the hint, hide the hint.
Use Text Input for focused data entry.
Don't use a Text Input as a viewing surface — only surface it when the user actively needs to enter or edit a value.
If a field requires complex context that cannot fit on screen, use a context button in the label to open a bottom sheet with more information.
Do not use a context button as a default way to explain fields — always try to surface the necessary information directly on the screen first e.g, with feedback message
General Component Behaviors
Labels
Labels indicate what type of data the field needs. Having labels present gives us two major advantages:
- They are programmatically associated with the field, which means assistive technologies will read them when the user focuses on them.
- When the user click/tap on the label, the browser passes the focus to the field, which makes it easier for touch screens, and users with motor disabilities.
Important note: Labels should always be present, unless for those cases where the context and elements that surround the input make it clear what data is needed (e.g. a search input close to a table or a list). In those cases, make sure an accessibility label is used.
Placeholders
Use the placeholders to help users understand the format needed. They can never be a substitute for the label or hint because:
- They disappear as soon as the user interacts with the field.
- They usually do not meet a strong contrast ratio (+3:1 in our case).
- Screen readers do not read placeholders as they do labels.
Feedback
The feedback area below the field can display either a hint or an error message — never both at the same time. A hint provides additional guidance to help the user fill the field correctly. An error message replaces it when validation fails.
Text Overflow
Single-line: When the input text is too long for the available horizontal space, it truncates with an ellipsis.
Multi-line: When the multiline prop is enabled, the field expands vertically to accommodate longer content. You can define the maximum number of lines displayed before the field becomes scrollable. A default max value of lines is 3.
Required or Optional
Text fields can be marked as optional, and those not marked optional are considered required.
Context button
If a field requires complex context to explain what it's asking for, you can add a context icon that opens a bottom sheet with more information.
Leading visual
The leading visual precedes the text input and displays consistently whether text has been entered or not. It can be an icon or a short text string.
Trailing visual or button
The trailing position follows the text input and displays consistently whether text has been entered or not. It can be:
- A non-interactive icon or text (trailing visual)
- An interactive button for simple actions like copying or clearing the field.
Keyboard Type
You can configure the Text Input to show a keyboard suited to the type of data the user is expected to enter. Always use the most specific type available as it reduces input errors and improves the experience, especially on small screens.
- Text -use for general text input such as names, messages, or descriptions. This is the default.
- Password -use for sensitive data like passwords or PINs. Input is masked to hide characters as they are typed.
- Email -use when the user needs to enter an email address. Shows a keyboard with quick access to @ and . characters.
- Phone -use when the user needs to enter a phone number. Shows a numeric dial-pad style keyboard.
- Number -use when the user needs to enter a purely numerical value, such as an age, quantity, or code.
- Search -use when the field is used to search or filter content. Shows a search action key on the keyboard.
States
Content Guidelines
- Keep it consistent. Use the same terms for similar concepts across your forms and inputs. If you call it "Zip Code" on one form, don't switch to "Postal Code" on another.
- Use sentence case. This improves readability and scannability compared to title case or all caps.
- Provide a call to action. The button to submit the form should have clear, actionable text like "Save" or "Sign Up," not just "Submit."
For further information, see the Content Styleguide.
Known Gaps
- Additional accessibility guidelines