Skip to content

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

Specification of MultiselectLookup.

MultiselectLookups include the following items:

  1. Input
    A predictive text input where the user types to look for the suggested results.
  2. Dropdown menu
    Results matching the input text are displayed within the Menu, allowing users to select one or more options to include as chips.
  3. 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:

  1. 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.
  2. 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.

MultiselectLookup types based on chip placement: chips within the input or chips separated from the input.

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.

MultiselectLookup with no matching results from the text typed.

Interaction states

MultiselectLookup has the following visually separate states:

Interaction states of MultiselectLookup: default, hover on input, focus-active,focused with one selected item, filled, hover on chip’s remove button, hover on chip, focused chip, disabled, error default, error hover, and error filled.

  1. Default
  2. Hover on input
  3. Focus or active
  4. Focused with one selected item
  5. Filled
  6. Hover on chip’s remove button
  7. Hover on chip
  8. Focused chip
  9. Disabled
  10. Error default
  11. Error hover
  12. 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.

“Invite users” Field with a MultiselectLookup showing two users included as chips.

Do:
  • Use MultiselectLookup to enable users to select multiple items from a menu with predefined options.

“Select a language” Field expecting one single chip selection from a MultiselectLookup.

Don't:
  • Use MultiselectLookup if only a single item input is anticipated. In this case, consider using alternative components like Lookup or Select instead.

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.

Demos

Configurable

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

  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 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:

  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.

Selected value: [ "Q81", "Q7540" ]

carrot
eggplant

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.

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:

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{}

Events

Event namePropertiesDescription
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.