MultiselectLookup
A MultiselectLookup is a predictive input that allows users to make multiple selections from a menu of options.
Guidelines
When to use MultiselectLookups
The MultiselectLookup allows users to filter information or fill out form data by selecting multiple items from a menu of options. Create chips by entering letters or words within the input field and selecting one or more options from the menu options that match the entered text. Remove chips by unselecting them from the open menu, clicking the added chip, or using its remove button.
When to use:
- When users need to simplify a complex filtering process by creating chips from a predefined list of options in a menu.
- When users need to enter text to get autocomplete suggestions and select more than one option from a menu.
When not to use:
- When users need to create custom chips that cannot be selected from a menu. Use ChipInput instead.
- When users need to select one single option from the menu. Instead, use Lookup or Select.
- When the filtering process is simple and involves a short list of options. For static options in a small list, consider using a Checkbox group instead.
Specifications
MultiselectLookups include the following items:
- Input
A predictive text input where the user types to look for the suggested results. - Dropdown menu
Results matching the input text are displayed within the Menu, allowing users to select one or more options to include as chips. - Chips
Selected results from the menu are included as chips in the input, and they are stacked next to each other. A chip can be removed by clicking within it or on its remove button.
Component limitations
The base min-width for the MultiselectLookup component is set at @size-1600
(equivalent to 256px
in the default Codex theme), but it can be customized to a smaller width if needed. There is no maximum width set. Chips can vary in length as needed and will expand in width based on text length, with ellipsis applied if text exceeds the available width. Chips may stack into multiple lines within the input when needed.
Refer to the MultiselectLookup component in Codex Figma.
Types
Placement of chips
Depending on the placement of the chips, there are two types of MultiselectLookup:
- Chips within the input field
In this case, selected options from the menu are added to the input field as chips, placed side by side. - Chips separated from the input field
In this case, the chips are placed in a light gray box above the input field once they are included.
No results
If there are no results for the text typed by the user, a non-interactive "no results" message will be displayed within the menu.
Interaction states
MultiselectLookup has the following visually separate states:
- Default
- Hover on input
- Focus or active
- Focused with one selected item
- Filled
- Hover on chip’s remove button
- Hover on chip
- Focused chip
- Disabled
- Error default
- Error hover
- Error filled
The error state must always be accompanied by an inline error message to ensure users are informed about the error and provides guidance to fix it. This message will be displayed when the MultiselectLookup is included within a Field.
Best practices
Consider the following recommendations when using MultiselectLookups.
- Use MultiselectLookup to enable users to select multiple items from a menu with predefined options.
- Use MultiselectLookup if only a single item input is anticipated. In this case, consider using alternative components like Lookup or Select instead.
Keyboard navigation
Key | Function |
---|---|
Tab | It moves the focus between the chips within the input. When the focus is placed on the last chip, it places the focus to the input. When an item from the menu is hovered, pressing Tab selects or deselects it. |
Shift + Tab | It moves the focus to the previous chip within the input or to the previous interactive element in the page. |
Left arrow + Right arrow | Arrow keys navigate between the chips within the input when they are focused. |
Up arrow + Down arrow | When the focus is placed on the input, it opens the menu. When the menu is open, pressing it navigates through menu options. |
Enter | When a chip is focused, it removes the chip. When an item from the menu is hovered, pressing Enter selects it. |
Esc | When any of the chips or input is focused, pressing Esc removes the focus from the focused element. When the menu is open, it closes the menu. |
Backspace | If the focus is placed on a chip, this key removes the chip and moves the focus to the previous chip. When the last chip is removed, it places the focus to the input. |
Demos
Configurable
Name | Value |
---|---|
Props | |
separateInput | |
status | |
disabled | |
readonly | |
View | |
Reading direction |
Basic usage
The MultiselectLookup component emits an event on input. The parent component should react by computing or fetching menu items, then providing those items to the MultiselectLookup component for display by updating the menu-items
prop. The user can then select an item from the menu.
The MultiselectLookup component is similar to the Lookup component, but there are some key differences to enable the selection of multiple items:
- The
selected
prop, which is bound withv-model
, is an array of selected values (or an empty array if there are no selections). - The
inputChips
prop must be bound viav-model
and is an array of chips representing each selected item (or an empty array if there are no selections).
There are 2 ways to listen for input changes:
- Listen for
input
events, like in the example below. Do this if you only need to know about the input when it changes. - Use
v-model
to bind theinputValue
prop and listen for eitherinput
orupdate:input-value
events. Do this if you need to know the current input value at other times, or if you want to be able to set the input value. Refer to the Vue usage tables for more information.
Items are displayed via the MenuItem component—refer to the MenuItem docs for more options. In this example, a menuConfig
object is passed to the Lookup to bold the label text. Note that in this example, menu items are Wikidata items with a human-readable label and a Wikidata entity ID value.
WARNING
The parent component must update the menu-items
prop after each input
event, otherwise the Lookup component will stay in the pending state indefinitely. If there are no results for the given input, set the menu-items
prop to an empty array ([]
).
Selected value: []
With fetched results
Often, MultiselectLookup is used to fetch results from an API endpoint. Parent components should react to the input
or update:input-value
event emitted by MultiselectLookup to search for results, then pass back to the MultiselectLookup either an array of results to display as menu items or an empty array if there are no results. After the input changes and until the menuItems are updated, a pending animation will display in the input.
Scrolling is enabled by setting the visibleItemLimit
property of the menuConfig
prop.
With scrolling enabled via the visibleItemLimit
property of the menuConfig
prop, when the user nears the end of the list of results, a load-more
event is emitted. The parent component can react to this by fetching more results and appending them to the list of menu items provided to the Lookup. These new items will then be displayed within the menu.
With suggestions
You can show a list of suggestions by passing in a group of menu items initially. The parent component must handle resetting the menu items to this list of suggestions when the input is cleared.
Selected value: []
With initial value
To set an initial selection, do the following:
- Set the
selected
prop to an array of selected values. - Set the
inputChips
prop to a set of chips matching the selected values.
Selected value: [ "Q81", "Q7540" ]
Form field
A MultiselectLookup can be wrapped in the Field component to add features like a semantic label, description and help text, validation messages, and more. Refer to the Field page for more information.
Other features
The MultiselectLookup component has an internal Menu and ChipInput. You can use the following features from those components in the MultiselectLookup component:
Vue usage
Attributes passed to input
This component will pass any HTML attributes applied to it, except for CSS class, to the <input>
element within the component.
Props
Prop name | Description | Type | Default |
---|---|---|---|
inputChips (required) | Current chips present in the input. Must be bound with v-model:input-chips . Initialize to an empty array if there are no initial selections. If there are, initialize to an array of input chips matching those selections. | ChipInputItem[] | |
selected (required) | Value(s) of the current selection(s). Must be bound with v-model:selected . Initialize to an empty array if there are no initial selections. | MenuItemValue[] | |
menuItems (required) | Menu items and/or menu group definitions. Initialize to an empty array if there are no initial menu items. Menu groups and individual menu items will be output in the order they appear here. | (MenuItemData|MenuGroupData)[] | |
inputValue | Current value of the text input. This prop is optional and should only be used if you need to keep track of the text input value for some reason (e.g. for validation). Optionally provided by v-model:input-value binding in the parent component. | string|number | null |
separateInput | Whether the text input should appear below the set of input chips. By default, the input chips are inline with the input. | boolean | false |
disabled | Whether the entire component is disabled. | boolean | false |
readonly | Whether the MultiselectLookup is readonly. | boolean | false |
status | status attribute of the input. | ValidationStatusType | 'default' |
menuConfig | Configuration for various menu features. All properties default to false. See the MenuConfig type. | MenuConfig | {} |
Events
Event name | Properties | Description |
---|---|---|
load-more | When the user scrolls towards the bottom of the menu. If it is possible to add or load more menu items, then now would be a good moment so that the user can experience infinite scrolling. | |
update:input-chips | inputChips ChipInputItem[] - The new set of inputChips | When the input chips change. |
update:selected | selected MenuItemValue[] - The new set of selected values | When the selected value changes. |
update:input-value | inputValue string|number - The new input value | When the input value changes. Only emitted if the inputValue prop is provided. This event is emitted both when the user changes the input and when the input is changed or cleared automatically (e.g. on selection). |
input | value string|number - The new value | When the user changes the value of the input. Not emitted when the input is changed automatically (e.g. on selection). |
change | event Event | When an input value change is committed by the user (e.g. on blur) |
focus | event FocusEvent | When the input comes into focus |
blur | event FocusEvent | When the input loses focus |
Slots
Name | Description | Bindings |
---|---|---|
menu-item | Display of an individual item in the menu | menu-item MenuItemData - The current menu item |
no-results | Message to show if there are no results to display. |