Skip to main content

Input

An input is a field that allows a user to enter and interact with text and numeric values.

Code documentation

Web

Anatomy

The input component is made up of 11 elements.

  1. Left slot
  2. Label
  3. Placeholder text
  4. Field
  5. Clear button
  6. Right slot
  7. Required indicator
  8. Helper text
  9. Value
  10. Error text
  11. Resizer
Anatomy diagram numbering 11 elements of an input.

Variants

Type

Text

The text input is the default type that allows a user to input a single line of text.

A label is positioned immediately above an input field. The label is aligned with the left edge of the field.

Password

Password inputs are based on the HTML password input type and used to obscure sensitive content within the input. The right icon slot is set to display an icon-only button with a show/hide icon by default, but can be customized. The right icon slot can also be hidden if that functionality is not needed. Passwords are masked by default.

Two inputs compare how a password is displayed. The top input obscures the password using a series of typographic bullets in place of the characters. An eye icon aligned to the right of the field denotes an action to reveal the password. The bottom input displays the word Password to represent readable password text. An eye icon with a diagonal slash through it denotes an action to hide the password.

Search inputs are based on the HTML search input type and used to provide semantic search capabilities. The left icon is set by default to a search icon for visual context and may be customized or hidden as needed.

An input includes a magnifying glass icon aligned to the left of the field is immediately followed by the word Search.

Text area

The text area type allows the user to enter and edit multiple lines of text. Left and right icons are not available for text areas.

An input includes a field that is tall enough for approximately three lines of text. The word Value represents a sample value within the field. Two small diagonal lines occupy the bottom-right corner of the field, indicating a way to resize the field.

Size

Small

Small inputs are used to reduce the overall height of the input field. They are recommended for forms with a high number of inputs or contexts that require more conservative vertical spacing.

An input includes a label and a field with sample value text. The field has top and bottom padding that is roughly equal to the line-height of the value.

Medium

Medium inputs are the default size.

An input includes a label and a field with sample value text. The field has top and bottom padding that is slightly taller than the line-height of the value.

Large

Large inputs are recommended for forms with a relatively limited number of inputs or to improve touch triggering.

An input includes a label and a field with sample value text. The field has top and bottom padding that is nearly twice the line-height of the value.

Label

Every input should have a label that describes the purpose of the input in a concise and clear manner. Built-in labels can be omitted if an adjacent label is included that adequately describes the purpose of the input and is correctly referenced to the field for accessibility purposes.

The top input displays a sample label immediately above an input field. The bottom input does not include a label.

Left slot

A left slot is available for an icon to describe the type of input required, such as a date picker, or as a touch target to trigger nested components. The left slot is available on all input types except text area. When the slot is hidden, the input text expands to fill the available space.

A sample icon is displayed to the left of a sample value to indicate the position of a left slot.

When interactivity is required, a button should be used within the slot. This ensures the appropriate interactions are automatically enabled and affords a focus area for easy keyboard navigation. Consider using small, tertiary, icon-only buttons for consistency and to compliment the rest of the input elements.

The top input includes a sample icon-only button without a container. The bottom input includes a sample icon-only button with a container and a focus ring. Both buttons are left-aligned within the field to indicate the position of a left slot.

Right slot

The right slot can accommodate an icon to describe the type of input required, such as a date picker. It can also provide additional functionality such as clearing the content of a field or as a touch target when additional functionality is present. The right slot is available on all input types except text area. When the slot is hidden, the input text expands to fill the available space.

A sample icon is displayed to the right of a sample value to indicate the position of a right slot.

The right slot can also accommodate a button when a micro interaction is required within the input. Consider using small, tertiary, icon-only buttons for consistency and to compliment the rest of the input elements.

The top input includes a sample icon-only button without a container. The bottom input includes a sample icon-only button with a container and a focus ring. Both buttons are right-aligned within the field to indicate the position of a right slot.

Clear button

A clear button can be enabled to allow users a way to quickly remove a value from the input field. When enabled, the button remains hidden until a value is entered into the input field and then persistently displays until the user clears the value. The clear button will not display when placeholder text is displayed. While the icon and button styling can be customized, the button itself is a persistent part of the input functionality and therefore cannot be customized.

The clear button always precedes the right icon slot.

Two inputs are compared side-by-side. The left input includes a label above a field that includes a sample value and a right-aligned icon that displays an X contained within a circle. The right input includes the same example with a second icon immediately to the right of the circled X.

Helper text

Helper text is used to convey additional information about the input such as input requirements or character counts.

Sample helper text is displayed between the label and the input field.

Required indicator

Inputs can be marked as either required or optional which triggers relevant validation on the form. The indicator is a preset and styled element within the component, not manually entered as part of the label string.

Required form elements are used when the majority of the form elements are optional, but a few need to be marked as required.

Optional form elements are used when the majority of the form elements are required, but a few elements need to be marked as optional.

Two inputs groups are compared top-to-bottom. The top input includes an indicator styled as a red asterisk to the right of the label. The bottom input includes an indicator with the word optional in parentheses to the right of the label.

Behavior

States

Inputs have five available base states:

  1. Enabled
  2. Focus
  3. Hover
  4. Active
  5. Disabled
The input component includes enabled, focus, hover, active, and disabled states.

Invalid

An invalid state can also be triggered on inputs to indicate that a value needs to be entered or that the entered value is invalid. Error text is always displayed as part of the invalid state to allow for a generic error message or provide specific guidance as to what needs to be fixed. Error text is always displayed in addition to any helper text that is present and below the input field.

A sample of red error text is displayed immediately below the input field.

Read-only

Inputs may be set to read-only for when form values need to be shown but shouldn’t be edited. Read-only content may still be copied by the user and hyperlinked content such as email addresses, URLs, and telephone numbers are still interactive. They are also part of the tab order and can receive focus.

The other configurable elements such as label, icons, and helper text can still be included and customized in a read-only input as needed.

On text areas, the resizer remains visible and functional.

An input is displayed with a label and sample value text. The input field has no visible border.

Placeholder

Placeholder text can be included to provide the user ancillary guidance on what should go into the input such as example text or a sample format for telephone numbers. Avoid displaying critical information within the placeholder as placeholder text disappears after the user begins entering data into the input. Placeholder text should not be used as a substitute for an input label.

Sample placeholder text is left-aligned within an input field.

Text overflow

Label

Label text that is longer than the available space wraps to a new line.

The input label text wraps to a second line when it meets the edge of an implied container around the input.

Value

Values that are longer than the input are handled using the behavior of native HTML inputs where the text is cropped by the interior boundaries of the input when it is not active. When the user activates the input, the full value becomes available and can be accessible via keyboard navigation or selection.

A single line of sample value text overflows the boundaries of the input field and is hidden beyond the field's rightmost edge.

Helper and error text

Helper and error text wrap to a new line when they are too long for available horizontal space.

The helper and error text of the input each wrap to a second line when they meet the edge of an implied container around the input.

Text area height

Scroll

By default, a text area will vertically scroll to accommodate text that overflows the text area’s boundaries. If the resizer is enabled, the dimensions of the text area can be resized by the user to allow more content to display. The scrollbar is the browser default and has no custom styling.

Three lines of sample value text are implied to overflow the fixed height of the text area's input field. A pill-shaped scrollbar is aligned just within the right edge of the field.

Auto grow

A text area can also be set to automatically grow to match the height of the content. A resizer can still be used with auto grow to momentarily override the dimensions of the text area. However, any change to the input text will cause the text area to “snap” back to the height of the content. When set to auto grow, a text area will not display a scrollbar even if the field is momentarily resized to crop the text.

The input field of a text area hugs multiple lines of sample value text.