MultiselectLookup β
A MultiselectLookup is a predictive input that allows users to make multiple selections from a menu of options.
Name | Value |
---|---|
Props | |
separateInput | |
status | |
disabled | |
readonly | |
View | |
Reading direction |
Overview β
When to use MultiselectLookup β
Use the MultiselectLookup component to let users search through a set of options to choose predefined values for a form field or to filter information. A MultiselectLookup is useful when there are many options the user can choose from, so they need to filter the items via a text query.
When to use:
- When users may only select values from a predefined list.
- When there are many predefined options to choose from.
- When users need to be able to select multiple items.
When not to use:
- When users need to create custom values that cannot be selected from a menu. Use ChipInput instead.
- When users need to select a 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.
About MultiselectLookup β
MultiselectLookup includes the following elements.
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.
- Include an initial list of 2β5 suggestions if it's helpful to users.
- Include a "no results" message if there are no results found for the current input value.
Chips β
Selected results from the menu are included as chips in the input. Individual chips can be removed to de-select their values. Chips can be placed within the input or in a separate section above the input.
Use the Field component
Wrap the MultiselectLookup within the Field component to incorporate features such as a label, description, help text, and inline validation messages.
Examples β
Basic usage β
The MultiselectLookup component emits an event when the user types in the input. The parent component can then fetch items matching that input and pass them to the MultiselectLookup to display in the Menu.
Developer notes
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 MultiselectLookup 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 MultiselectLookup 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 ([]
).
Open the console, where the current selection is output each time an item is selected or de-selected.
With keep input on selection β
By default, when the user makes a selection, the input will be cleared and the menu will be closed. Sometimes, it might be more helpful to enable users to select multiple items based on the same search term. In these cases, use the keepInputOnSelection
prop, which will keep the same input and make the menu stay open on selection.
With fetched results β
Often, MultiselectLookup is used to fetch results from an API endpoint, and may display many results. You can control how many items to show in the menu at once, and other items can be reached by scrolling. You can also load more items when the user scrolls to the end of the menu.
Developer notes
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 MultiselectLookup. These new items will then be displayed within the menu.
With suggestions β
You can show a list of 2β5 initial suggestions if it's helpful.
Developer notes
To show a list of suggestions, pass in an array of menu items initially. The parent component must handle resetting the menu items to this list of suggestions when the input is cleared.
With initial value β
Developer notes
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.
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.
- Automatically display an inline warning message if the entered text doesn't match any item from the MultiselectLookup's menu, and show an error after form submission.
- Provide an error message that provides guidance on fixing the issue.
Other features β
The MultiselectLookup component has an internal Menu and ChipInput. You can use the following features from those components in the MultiselectLookup component:
Technical implementation β
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 | {} |
keepInputOnSelection | Whether to keep the search term in the input after selection. | boolean | false |
Events β
Event name | Properties | Description |
---|---|---|
chip-click | chip ChipInputItem - The clicked chip | When a chip is clicked. |
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. |
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. |