Anatomy
Learn about the individual parts of typeahead multi.
Typeahead multi field
- Label: Text that identifies the type of item that the user is selecting; 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): Color label with an optional icon to indicate status or category
- Selected list item: A typeahead multi-specific pill containing an item selected from the dropdown; appears in the input field
- Slot (optional): Displays additional actions or decorative elements
- Dynamic text area: Space where the user enters text; a dropdown opens and responds dynamically as the user adds text
Dropdown list
- Dropdown list container: Contains the list items
- Section header (optional): An area for additional details about the displayed results
- Avatar (optional): Optional avatar to identify the list item
- Selected list item: Checkmark icon indicating a selected list item
- List item label: Primary information about a list item
- List Item sub-label (optional): Supplemental information in a dropdown list item
Usage
Use typeahead multi to help a user quickly fill an input field with multiple items by narrowing down many results of a similar type. Typeahead multi can be used for tasks that involve predefined lists such as assigning multiple people to a team.
Form fields
Typeahead can be used as a single form field or part of a group of related form fields.
Variants
Learn about the variants of typeahead multi.
Types
Typeahead multi is a version of the typeahead component. For more information on this base component, see usage guidance for typeahead.
Sizes
Typeahead multi has the following sizes: small and medium (default).
Small
Use the small size for areas that have limited space. When you select the small size, all typeahead multi-specific pills that appear in the field are automatically set to the small size. The typeahead multi-specific pill component will have an extra-small avatar (if included), reduced font size, small icon, and an extra-small presence icon (if included).
Medium
Use the medium size alongside similarly sized components and content.
Note: Medium is the default size for typeahead multi.
Configurations
Learn how to customize typeahead multi by configuring the available properties. All configurations for typeahead are also available for typeahead multi.
See usage guidelines for typeahead.
Slots
The typeahead multi input field slot can appear at the beginning or end of an input field. You can add up to three field decorators that are associated with the typeahead input field.
This example shows an AI icon used to indicate the value was AI generated.
Placeholder text
You can add unique placeholder text for each input field. Placeholder text should be a hint that supplements the label. This could be the suggested format for the expected input or guidance on how to complete the field. The placeholder text disappears when the user enters the first character.
Optional indicator
You can configure an input field as optional to indicate the user isn't required to select a value in this field to complete the form. Optional fields will display "(Optional)" text next to the form label.
Note: Don't use this indicator in conjunction with the required field indicator.
Required indicator
You can configure an input field as required with an asterisk indicator after the form label. The user must enter a value in a required field to complete the form. When the user hovers over the asterisk, a tooltip appears and displays "Required."
Note: Don't use this indicator in conjunction with the optional field indicator.
Highlighted value
You can enable typeahead multi to display the highlighted value component above the dynamic text area. It can be used to display brief status or category content.
Read-only field
You can configure an input field as read-only to indicate that the user can’t modify the value in this field. However, users can select and copy the values in the input field. If the input field doesn't contain a value, it displays an em dash (—) to denote an empty value. When the user hovers over the field a tooltip appears and displays “Read-only.”
Disabled field
You can disable an input field which makes the field unavailable for user interaction.
Invalid field
Use to show when the user enters an invalid input. Typically, it indicates an error has occurred.
Field helper text
You can add an information button iconic next to the form label. Use the field helper text to display information needed for guiding users on how to complete the field. This can include formatting guidance, requirements, or an explanation of the input field's purpose. The helper text will display in a popover when the user selects the information icon.
See usage guidance for popover
Field layout
You can configure the field layout to be horizontal or vertical. The default field layout is “vertical”.
Example of horizontal layout
Field messages
You can configure custom messages to appear under the typeahead input field. These messages provide users with information about errors, helpful suggestions, or information for completing the input field.
Auto-focus
Use this configuration to automatically place focus on an input field when a user opens the page.
Disable auto-close
You can configure the dropdown to remain open until the user manually dismisses it (by selecting escape, tab, or clicking outside the component). Disabling auto-close enables user to select multiple typeahead multi-specific pills at the same time without closing the dropdown.
Search behavior
You can choose a type of search behavior for your use case. The chosen search behavior instructs the dropdown how to respond as the user enters text into the input field. Typeahead search behavior: managed, initial, and contains.
For more details on search behavior, See usage guidelines for typeahead.
Avatar
The dropdown list and result pills can be configured to show associated avatars. Avatar should only be used if it is relevant to the dropdown list items.
This avatar configuration is specific to typeahead multi.
Behavior
Learn how typeahead multi behaves when the display changes or a user interacts with the component.
States
Typeahead multi has the same states as typeahead for the input field and dropdown list items. For information on input field states, dropdown list item states, and highlighted states, see usage guidance for typeahead.
Result pill
The typeahead multi-specific result pill has the following states.
| State | Example |
|---|---|
| Default |  |
| Hover |  |
| Focus |  |
| Read Only |  |
| Disabled |  |
Responsive behaviors
Typeahead multi inherits the width of its container and resizes with the container.
Input field overflow
When the number of result pills exceeds the width of the input field, the input field area will increase in height to accommodate more result pills. A maximum height can be set on the input field area to allow for scrollbar behavior.
Interactions
Users can interact with typeahead multi through the input field and dropdown list. This includes any field decorators.
Selection
Users can select the input field to open the dropdown list, use typeahead multi to filter list items, and select items to populate the input field as result pills.
Note: A user can choose to enter a full list item into the input field to generate a complete match in the dropdown. If this method is used, the user can select outside the input field to close the dropdown and fill the input field with the chosen list item.
Deselection
Users can deselect a result pill by directly selecting the dismiss button “x” on the typeahead multi-specific pill or by selecting a result pill and pressing the Backspace or Delete key. When a result pill is deselected, the pill disappears from the input field area and the value no longer has the check indicator beside it in the dropdown.
Truncation
When text in typeahead exceeds the width of the container or content area, the text truncates with an ellipsis, and a tooltip shows the full content on hover. The form label also will truncate when it exceeds the input field width or when the label indicators prevent the full label from displaying.
Dropdown list text wrap
Dropdown section header text, list items, and sub-labels wrap when they reach the end of the panel.
Design recommendations
Learn how to apply typeahead multi in your design.
Do use typeahead multi when users are able to select more than one input item.
Don't use typeahead multi if the user can only select one input item. If there are only a few options, use a dropdown or select instead.
Do use typeahead multi to help users select items from a list of related items.
Don't use typeahead multi if the items in the dropdown list cannot be relevantly grouped. For fields that require more open-ended results, use an input field without typeahead.
UI text guidelines
Typeahead multi uses the input component. 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.”
Usability
Typeahead complies with all internationalization and accessibility requirements.
Internationalization
When the display translates to a right-to-left (RTL) language, the contents of the typeahead multi input field and dropdown flip sides. This includes text and field decorators.
Accessibility
Learn how to access the actionable elements of typeahead multi through keyboard interactions and screen readers.
Keyboard interactions
You can access the actionable elements of typeahead with these keyboard interactions:
- Tab or shift + tab: Moves between the typeahead field and any interactive elements in the standard tab order
When the focus is in typeahead input field:
- Enter: Toggles the dropdown open or closed
- Arrow down: Opens the dropdown
- Delete/backspace (if result pills are in the input): Brings focus to the most recent result pill; the pill is deleted if the delete/backspace is pressed again
When the focus is in the dropdown:
- Arrow down: Moves focus to next list value
- Arrow up: Moves focus to previous list value; closes the dropdown if the focus was on the first list value
- Enter: Selects the focused list value and closes the dropdown
- Escape: Collapses the dropdown and moves focus to the input field
- Tab: Collapses the dropdown and moves focus to the next interactive element in the tab order
- Home: Moves focus to the first option and selects it
- End: Moves focus to the last option and selects it
When the focus is on a result pill:
- Arrow right and arrow left: Moves focus to the next or previous result pill
- Delete/backspace: Deselects the result pill and removes it from the input field
- Enter (when focus is on a result pill's dismiss button): Deletes the result pill
Screen readers
When you apply ARIA labels to a component, screen readers announce the controls and contents of typeahead in the prescribed tab order.