Skip to main content

Input - Search

A search input is a single-line text field with iconography and behaviors to support search functionality.

BetaInput replaces the search type of input from v1.

Code documentation

Web

Anatomy

The input component is made up of 13 elements.

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

Variants

Size

The size of the input can be adjusted to accommodate a variety of space constraints. These sizes use fixed dimensions to guarantee that the height doesn't grow based on the content of the input field. This ensures that all form elements of the same size compliment and predictably align with each other.

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.

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.

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.

An input includes an indicator styled as a red asterisk to the right of the label.

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

An input includes an indicator with the word optional in parentheses to the right of the label.

Helper text

Helper text is used to convey additional information about the input such as format requirements.

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

Helper text wraps to a new line when it's too long for the available horizontal space.

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

Left slot

A left slot is available for an icon to visually describe the input as a search input. A default icon is supplied, but can be overridden with a custom icon if required. 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.

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.

Because of the accessibility issues that can result, placeholder text is not supported. When examples or additional instructions are needed, consider using the input's helper text or other supplemental text within the surrounding content.

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. 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 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 clear button always precedes the right slot.

The 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. A second icon is positioned immediately to the right of the circled X.

Right slot

The right slot can accommodate an icon to further describe the type of input required.

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.

When the slot is hidden, the input text expands to fill the available space.

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

Inputs can be set to invalid 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. It is also 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.

Error text wraps to a new line when it's too long for the available horizontal space.

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

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. They are also part of the tab order and can receive focus.

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

Figma

See the notes for base input for guidance on how to work with common input elements.