Skip to content

MultiselectLookup ​

A MultiselectLookup is a predictive input that allows users to make multiple selections from a menu of options.

NameValue
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.

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:

  1. The selected prop, which is bound with v-model, is an array of selected values (or an empty array if there are no selections).
  2. The inputChips prop must be bound via v-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:

  1. Listen for input events, like in the example below. Do this if you only need to know about the input when it changes.
  2. Use v-model to bind the inputValue prop and listen for either input or update: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 ​

carrot
eggplant

Developer notes

To set an initial selection, do the following:

  1. Set the selected prop to an array of selected values.
  2. 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.
Filter results by namespace

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 nameDescriptionTypeDefault
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)[]
inputValueCurrent 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|numbernull
separateInputWhether the text input should appear below the set of input chips.

By default, the input chips are inline with the input.
booleanfalse
disabledWhether the entire component is disabled.booleanfalse
readonlyWhether the MultiselectLookup is readonly.booleanfalse
statusstatus attribute of the input.ValidationStatusType'default'
menuConfigConfiguration for various menu features. All properties default to false.

See the MenuConfig type.
MenuConfig{}
keepInputOnSelectionWhether to keep the search term in the input after selection.booleanfalse

Events ​

Event namePropertiesDescription
chip-clickchip ChipInputItem - The clicked chipWhen a chip is clicked.
load-moreWhen 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-chipsinputChips ChipInputItem[] - The new set of inputChipsWhen the input chips change.
update:selectedselected MenuItemValue[] - The new set of selected valuesWhen the selected value changes.
update:input-valueinputValue string|number - The new input valueWhen 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).
inputvalue string|number - The new valueWhen the user changes the value of the input. Not emitted when the input is changed automatically (e.g. on selection).
changeevent EventWhen an input value change is committed by the user (e.g. on blur)
focusevent FocusEventWhen the input comes into focus
blurevent FocusEventWhen the input loses focus

Slots ​

NameDescriptionBindings
menu-itemDisplay of an individual item in the menumenu-item MenuItemData - The current menu item
no-resultsMessage to show if there are no results to display.

Keyboard navigation ​

KeyFunction
TabIt 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 + TabIt moves the focus to the previous chip within the input or to the previous interactive element in the page.
Left arrow + Right arrowArrow keys navigate between the chips within the input when they are focused.
Up arrow + Down arrowWhen the focus is placed on the input, it opens the menu. When the menu is open, pressing it navigates through menu options.
EnterWhen a chip is focused, it removes the chip. When an item from the menu is hovered, pressing Enter selects it.
EscWhen 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.
BackspaceIf 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.