Anatomy
- Label: (Optional) Descriptive text that helps users understand what information to enter in to the field
- Leading Icon: (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
- Trailing Icon: (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
Usage Guidelines
When to use this component
- Use an input when a user needs to enter a single line of text or a number. This is for standard user-generated content like names, email addresses, search queries, or numerical values.
- Use an input when the user needs to enter an unknown value, rather than selecting from a predefined list.
- Use an 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 content that requires multiple lines of text, such as a message or a description. A Textarea is the correct component for this.
-
Don't use an input for complex selections, like a date or a range of values. A specialized component like a Date Picker is more user-friendly.
Best Practices
Use input fields where the expected data is short.
Don't use the input field when the expected data is longer. Use the Textarea instead.
Use labels to specify the data required in the input field.
Do not avoid labels as they are essential to the input completion and later understanding.
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 hints to provide useful information about the required input.
Do not duplicate information, if an error message is repeating the hint, hide the hint.
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 aria-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.
Hint & errors
Hints and error messages provide additional directions to support the label meaning in an accessible manner.
Text Overflow
When the field text is too long for the available horizontal space, it truncates.
Required or Optional
Text fields can be marked as optional, and those not marked optional are considered required.
Tooltip
The tooltip trigger can be placed after the label or to the right of the field.
Leading Icon or Prefix
The leading icon or Prefix proceeds text input into a field and displays consistently, whether text is inputted or not.
Trailing Icon or Suffix
The trailing icon or Suffix comes after text input into a field and displays consistently, whether text is inputted or not.
Button
An input can hold an Icon Button in place of the trailing icon, in order to allow a user to do simple action, like copy information.
Do not change the button type or size or it will break the component.
Responsive Behavior
Inputs are designed to be responsive, shrinking to fit the available browser space. As the container shrinks, the input's horizontal padding and margins decrease to preserve space. If the content exceeds the input's width, it will be truncated with an ellipsis to maintain a clean layout.
When the input hits a mobile breakpoint the container padding becomes larger to accommodate mobile touch points and the text size increases.
States
Type
The most common types of input have been prebuilt for ease of use. If an input need is outside one of these types, use the basic input to create it.
Text
Password
Telephone
Number
Search
Date
Time
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
- Component enhancement
- Disabled and non-editable states
- Additional accessibility guidelines