Anatomy
- Label: Text that identifies the expected user input; a label must be present for accessibility, either as the component's label element or external to the component
- Required indicator (optional): Field decorator that indicates if a field is required
- Information button (optional): Opens a popover and shows the field helper text
- Highlighted value (optional): A color label with an optional icon to indicate status or category
- Slot (optional): Placeholder for displaying additional components
- Input field: Space for user input or placeholder text
- Value: Text entered by a user
Subcomponents
See usage guidance for button iconic
See usage guidance for dropdown
Usage
You can use input in many different areas where a user needs to enter information.
Forms
Use input in a form to collect information like name, address, and email.
Emails
Input fields used for email addresses are default text entries. You can add a field decorator to the input field slot to provide the user with a visual cue.
IP addresses
Input fields used for IP addresses are default text entries. Remember to allow periods as a valid user input.
Currency
Currency is a number-type entry and is accompanied by a dropdown for country selection. Remember to allow periods and any currency symbols (such as a dollar sign) as valid user inputs.
Variants
Learn about the attributes of input.
Types
Input is only one type of the input field component.
See usage guidance for input phone
See usage guidance for input URL
See usage guidance for input password
See usage guidance for textarea
Sizes
Input has two sizes: small (sm) and medium (md). Choose a size that fits with your display and complements the surrounding content. Remember to choose a size that supports the length of the expected user input, including any labels or decorators.
Small
Use the small size for areas that have limited space. The small size reduces the font size of the text.
Medium
Use the medium size alongside similarly sized components and content.
Note: Medium is the default size.
Configurations
Learn how to customize input field by configuring the available properties.
Slots
The input field slot can appear at the beginning or end of an input field. This space can include up to 2 decorator icons and a dropdown trigger.
This example shows how a dropdown would appear if the input slot is at the beginning of the input field.
This example shows how a dropdown would appear if the input slot is at the end of the input field.
This example shows an AI icon used to indicate the value was AI generated. Two additional icons are displayed at the end slot.
Input field formatting
You can configure an input field to accept different types of data, like text, numbers, and symbols. Additionally, you can restrict the type of characters that the input field accepts. The type of data you choose to include or restrict depends on the type of information you want the user to enter.
In this example, the input field allows users to enter a period because it is asking for a currency.
Placeholder text
You can add placeholder text to provide users with guidance on the type of input and expected format. The placeholder text disappears when the user enters a character.
Text align
You can configure the text alignment of placeholder and input text. Text align options are: Start (default), center, and end.
Note: Text align options “center” and “end” mustn’t be used in conjunction with decorators, such as the search magnifying glass.
Start alignment
Center alignment
End alignment
Required indicator
You can configure an input field as required with an asterisk indicator after the form label. This indicates that the user must enter a value in this field.
Note: This indicator shouldn’t be used with the optional field indicator.
Optional indicator
You can configure an input field as optional. When used, optional fields display "(Optional)" text next to the label. Add this indicator to an optional field when all other fields are required by default. However, you can show the user that a field is optional without displaying the indicator at all.
Note: This indicator shouldn’t be used with the required field indicator.
Field helper text
Use the field helper text to display guidance information to help users complete the field. The helper text will display in a popover when the information icon is activated.
Field layout
You can configure the field layout to be horizontal or vertical. The default field layout is “vertical”.
Field messages
You can configure custom messages to appear beneath the input field. These provide users with error messages, helpful suggestions, guidance, or information for completing the input field.
All field messages can include an icon, which always appears at the beginning of the text.
| Message type | Example |
|---|---|
| Error |  |
| Warning |  |
| Field information |  |
| Positive message |  |
| System message |  |
Design recommendations
Learn how to apply input field in your design.
Use a label to explain the purpose of the input field.
Avoid using placeholder text as a label for the input field.
UI text guidelines
These are some recommendations for using text within input.
Label
- Use a label that describes the expected input or a question you’re asking the person
Form field messaging
- Informational message
- Use clear and concise language to help the person fill out the input
- For example, “Only use letters and numbers in your username.”
- Use clear and concise language to help the person fill out the input
- Warning message
- Include information that helps the person understand any consequences or next steps
- Use present tense since this message shows up before any input.
- For example, “Credit card information will only be used for purchasing purposes.”
- Error message
- Avoid blaming the person. Instead, tell them what happened and how they can fix it.
- Use past tense since this message shows up after the person enters something
- For example, “Someone used this name already. Try entering a different name.”
Field helper text
- Provide additional information to help the person understand the field and what they're expected to input
- Avoid putting critical information in an Information icon because they aren’t always visible
Placeholder text
- Use sparingly because it will disappear once the person puts their cursor in the input field
- Format placeholder text as an example of what should go in the input or a brief description of how to complete the field
- For example, “Enter what has changed in this version of the app.”
Behavior
Learn how Input behaves when the display changes or a user interacts with the component.
States
Input has the following states: default, hover, focus, read-only, disabled, and invalid.
Users cannot edit the value when the input field is in a read-only state. However, users can select and copy the value. If a read-only input doesn't contain a value, it displays an em dash (—) to denote an empty value.
| State | Example |
|---|---|
| Default |  |
| Hover |  |
| Focus |  |
| Read-only |  |
| Disabled |  |
| Invalid |  |
Responsive behaviors
Input resizes based on the width of its container.
Interactions
Learn how Input responds when a user interacts with it.
Invalid state
In an invalid state, the label and indicator of a required input field appears in red. If the label includes either a required indicator or an optional indicator, it also appears in red. Use an invalid message to help the user resolve the error. The invalid message appears under the input field and can be customized to fit your experience and audience.
In this example, the input is invalid and a message is provided to help the user resolve the error.
Information button
If you’ve configured helper content, a user can select the information button to view additional information or suggestions for the expected input.
In this example, the field helper suggests appropriate input for the field.
Truncation
The label will truncate when it exceeds the input width or when the label options prevent the full label from displaying.
In this example, the required field indicator and information icon prevent the label from fully displaying. Therefore, it truncates with an ellipsis, and the full label is available in a tooltip on hover.
Usability
Input field complies with all internationalization and accessibility requirements.
Internationalization
When the display translates to a right-to-left (RTL) language, the label aligns on the right. Any decorators or options in the input field slot flip their order and align with the label on the right.
If there is a dropdown option in the input field slot, it also aligns on the right. The selections in the dropdown list also realign on the right.
Accessibility
Learn how to access the actionable elements of input field through keyboard interactions and screen readers.
Keyboard interactions
- Tab or Shift + Tab: Moves between the input field and any interactive elements in the standard tab order
Note: An option in the user Preferences menu on the OS sets a tab stop on non-interactive text that truncates, such as a title or label, and makes that text a tooltip trigger. The user presses Enter or the spacebar to open the tooltip and view the entire content. To enable this feature, set the Enable keyboard focus on truncated text option to true in the Accessibility panel of the Preferences menu
When the focus is in text input field:
- Arrow right/left: Moves the text entry caret across available text
- Arrow up/down: Moves the text entry caret through rows of available text (if applicable)
- Shift + Control/Command: Selects text
- Shift + Arrow right/left: Selects one character at a time
Screen readers
- Assign the aria-label or aria-labeledby attribute to input field to allow screen readers to provide additional context for that form field
- Assign the aria-describedby attribute to contents of field helper; this provides supplementary user guidance for the content required in the input field
- Assign the aria-required to required field indicator and set to "true"; by default, aria-required is set to "false"
- Assign the aria-invalid to "true" to alert when a field is marked as returning an error; by default, aria-invalid is set to "false"