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:

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.

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:

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.

Do:

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

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

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

• No results found.

Name	Value
Props
separateInput
status	default error
disabled
View
Reading direction	Left to right (LTR) Right to left (RTL)

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

• No results found.

NPM

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Selected value: {{ selection }}
		</p>

		<cdx-multiselect-lookup
			v-model:input-chips="chips"
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			aria-label="MultiselectLookup basic demo"
			@input="onInput"
		>
			<template #no-results>
				No results found.
			</template>
		</cdx-multiselect-lookup>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxMultiselectLookup } from '@wikimedia/codex';
import vegetableItems from '../../lookup/examples/data.json';

export default defineComponent( {
	name: 'MultiselectLookupBasic',
	components: {
		CdxMultiselectLookup
	},
	setup() {
		const chips = ref( [] );
		const selection = ref( [] );
		const menuItems = ref( [] );

		const menuConfig = {
			boldLabel: true,
			visibleItemLimit: 6
		};

		/**
		 * On input, filter the menu items.
		 *
		 * @param {string} value
		 */
		function onInput( value ) {
			if ( value ) {
				menuItems.value = vegetableItems.filter( ( item ) =>
					item.label.includes( value )
				);
			} else {
				menuItems.value = [];
			}
		}

		return {
			chips,
			selection,
			menuItems,
			menuConfig,
			onInput
		};
	}
} );
</script>

MediaWiki

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Selected value: {{ selection }}
		</p>

		<cdx-multiselect-lookup
			v-model:input-chips="chips"
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			aria-label="MultiselectLookup basic demo"
			@input="onInput"
		>
			<template #no-results>
				No results found.
			</template>
		</cdx-multiselect-lookup>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxMultiselectLookup } = require( '@wikimedia/codex' );
const vegetableItems = require( '../../lookup/examples/data.json' );

module.exports = defineComponent( {
	name: 'MultiselectLookupBasic',
	components: {
		CdxMultiselectLookup
	},
	setup() {
		const chips = ref( [] );
		const selection = ref( [] );
		const menuItems = ref( [] );

		const menuConfig = {
			boldLabel: true,
			visibleItemLimit: 6
		};

		/**
		 * On input, filter the menu items.
		 *
		 * @param {string} value
		 */
		function onInput( value ) {
			if ( value ) {
				menuItems.value = vegetableItems.filter( ( item ) =>
					item.label.includes( value )
				);
			} else {
				menuItems.value = [];
			}
		}

		return {
			chips,
			selection,
			menuItems,
			menuConfig,
			onInput
		};
	}
} );
</script>

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.

• No results found.

NPM

<template>
	<cdx-multiselect-lookup
		v-model:input-chips="chips"
		v-model:selected="selection"
		v-model:input-value="inputValue"
		:menu-items="menuItems"
		:menu-config="menuConfig"
		placeholder="Search wikidata items"
		aria-label="MultiselectLookup with fetched results demo"
		@input="onInput"
		@load-more="onLoadMore"
	>
		<template #no-results>
			No results found.
		</template>
	</cdx-multiselect-lookup>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxMultiselectLookup } from '@wikimedia/codex';

export default defineComponent( {
	name: 'MultiselectLookupWithFetch',
	components: {
		CdxMultiselectLookup
	},
	setup() {
		const chips = ref( [] );
		const selection = ref( [] );
		const inputValue = ref( '' );
		const menuItems = ref( [] );

		const menuConfig = {
			boldLabel: true,
			visibleItemLimit: 6
		};

		/**
		 * Get search results.
		 *
		 * @param {string} searchTerm
		 * @param {number} offset Optional result offset
		 *
		 * @return {Promise}
		 */
		function fetchResults( searchTerm, offset ) {
			const params = new URLSearchParams( {
				origin: '*',
				action: 'wbsearchentities',
				format: 'json',
				limit: '10',
				props: 'url',
				language: 'en',
				search: searchTerm
			} );
			if ( offset ) {
				params.set( 'continue', String( offset ) );
			}
			return fetch( `https://www.wikidata.org/w/api.php?${ params.toString() }` )
				.then( ( response ) => response.json() );
		}

		/**
		 * Handle lookup input.
		 *
		 * TODO: this should be debounced.
		 *
		 * @param {string} value The new input value
		 */
		function onInput( value ) {
			// Clear menu items if the input was cleared.
			if ( !value ) {
				menuItems.value = [];
				return;
			}

			fetchResults( value )
				.then( ( data ) => {
					// Make sure this data is still relevant first.
					if ( inputValue.value !== value ) {
						return;
					}

					// Reset the menu items if there are no results.
					if ( !data.search || data.search.length === 0 ) {
						menuItems.value = [];
						return;
					}

					// Build an array of menu items.
					const results = data.search.map( ( result ) => {
						return {
							label: result.label,
							value: result.id,
							description: result.description
						};
					} );

					// Update menuItems.
					menuItems.value = results;
				} )
				.catch( () => {
					// On error, set results to empty.
					menuItems.value = [];
				} );
		}

		function deduplicateResults( results ) {
			const seen = new Set( menuItems.value.map( ( result ) => result.value ) );
			return results.filter( ( result ) => !seen.has( result.value ) );
		}

		function onLoadMore() {
			if ( !inputValue.value ) {
				return;
			}

			fetchResults( inputValue.value, menuItems.value.length )
				.then( ( data ) => {
					if ( !data.search || data.search.length === 0 ) {
						return;
					}

					const results = data.search.map( ( result ) => {
						return {
							label: result.label,
							value: result.id,
							description: result.description
						};
					} );

					// Update menuItems.
					const deduplicatedResults = deduplicateResults( results );
					menuItems.value.push( ...deduplicatedResults );
				} );
		}

		return {
			chips,
			selection,
			inputValue,
			menuItems,
			menuConfig,
			onInput,
			onLoadMore
		};
	}
} );
</script>

MediaWiki

<template>
	<cdx-multiselect-lookup
		v-model:input-chips="chips"
		v-model:selected="selection"
		v-model:input-value="inputValue"
		:menu-items="menuItems"
		:menu-config="menuConfig"
		placeholder="Search wikidata items"
		aria-label="MultiselectLookup with fetched results demo"
		@input="onInput"
		@load-more="onLoadMore"
	>
		<template #no-results>
			No results found.
		</template>
	</cdx-multiselect-lookup>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxMultiselectLookup } = require( '@wikimedia/codex' );

module.exports = defineComponent( {
	name: 'MultiselectLookupWithFetch',
	components: {
		CdxMultiselectLookup
	},
	setup() {
		const chips = ref( [] );
		const selection = ref( [] );
		const inputValue = ref( '' );
		const menuItems = ref( [] );

		const menuConfig = {
			boldLabel: true,
			visibleItemLimit: 6
		};

		/**
		 * Get search results.
		 *
		 * @param {string} searchTerm
		 * @param {number} offset Optional result offset
		 *
		 * @return {Promise}
		 */
		function fetchResults( searchTerm, offset ) {
			const params = new URLSearchParams( {
				origin: '*',
				action: 'wbsearchentities',
				format: 'json',
				limit: '10',
				props: 'url',
				language: 'en',
				search: searchTerm
			} );
			if ( offset ) {
				params.set( 'continue', String( offset ) );
			}
			return fetch( `https://www.wikidata.org/w/api.php?${ params.toString() }` )
				.then( ( response ) => response.json() );
		}

		/**
		 * Handle lookup input.
		 *
		 * TODO: this should be debounced.
		 *
		 * @param {string} value The new input value
		 */
		function onInput( value ) {
			// Clear menu items if the input was cleared.
			if ( !value ) {
				menuItems.value = [];
				return;
			}

			fetchResults( value )
				.then( ( data ) => {
					// Make sure this data is still relevant first.
					if ( inputValue.value !== value ) {
						return;
					}

					// Reset the menu items if there are no results.
					if ( !data.search || data.search.length === 0 ) {
						menuItems.value = [];
						return;
					}

					// Build an array of menu items.
					const results = data.search.map( ( result ) => {
						return {
							label: result.label,
							value: result.id,
							description: result.description
						};
					} );

					// Update menuItems.
					menuItems.value = results;
				} )
				.catch( () => {
					// On error, set results to empty.
					menuItems.value = [];
				} );
		}

		function deduplicateResults( results ) {
			const seen = new Set( menuItems.value.map( ( result ) => result.value ) );
			return results.filter( ( result ) => !seen.has( result.value ) );
		}

		function onLoadMore() {
			if ( !inputValue.value ) {
				return;
			}

			fetchResults( inputValue.value, menuItems.value.length )
				.then( ( data ) => {
					if ( !data.search || data.search.length === 0 ) {
						return;
					}

					const results = data.search.map( ( result ) => {
						return {
							label: result.label,
							value: result.id,
							description: result.description
						};
					} );

					// Update menuItems.
					const deduplicatedResults = deduplicateResults( results );
					menuItems.value.push( ...deduplicatedResults );
				} );
		}

		return {
			chips,
			selection,
			inputValue,
			menuItems,
			menuConfig,
			onInput,
			onLoadMore
		};
	}
} );
</script>

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

• Suggested items
  • potatoroot vegetable
  • carrotroot vegetable, usually orange in color
  • zucchiniEdible summer squash, typically green in colour

NPM

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Selected value: {{ selection }}
		</p>

		<cdx-multiselect-lookup
			v-model:input-chips="chips"
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			aria-label="MultiselectLookup with suggestions demo"
			@input="onInput"
		>
			<template #no-results>
				No results found.
			</template>
		</cdx-multiselect-lookup>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxMultiselectLookup } from '@wikimedia/codex';
import vegetableItems from '../../lookup/examples/data.json';

export default defineComponent( {
	name: 'MultiselectLookupWithSuggestions',
	components: {
		CdxMultiselectLookup
	},
	setup() {
		const chips = ref( [] );
		const selection = ref( [] );
		// Set up an array of initial menu items to show as suggestions.
		const initialMenuItems = [
			{
				label: 'Suggested items',
				items: vegetableItems.slice( 0, 3 )
			}
		];
		const menuItems = ref( initialMenuItems );
		const menuConfig = {
			boldLabel: true,
			visibleItemLimit: 6
		};

		/**
		 * On input, filter the menu items.
		 *
		 * @param {string} value
		 */
		function onInput( value ) {
			if ( value ) {
				menuItems.value = vegetableItems.filter( ( item ) =>
					item.label.includes( value )
				);
			} else {
				// When the input is cleared, show the suggestions again.
				menuItems.value = initialMenuItems;
			}
		}

		return {
			chips,
			selection,
			menuItems,
			menuConfig,
			onInput
		};
	}
} );
</script>

MediaWiki

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Selected value: {{ selection }}
		</p>

		<cdx-multiselect-lookup
			v-model:input-chips="chips"
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			aria-label="MultiselectLookup with suggestions demo"
			@input="onInput"
		>
			<template #no-results>
				No results found.
			</template>
		</cdx-multiselect-lookup>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxMultiselectLookup } = require( '@wikimedia/codex' );
const vegetableItems = require( '../../lookup/examples/data.json' );

module.exports = defineComponent( {
	name: 'MultiselectLookupWithSuggestions',
	components: {
		CdxMultiselectLookup
	},
	setup() {
		const chips = ref( [] );
		const selection = ref( [] );
		// Set up an array of initial menu items to show as suggestions.
		const initialMenuItems = [
			{
				label: 'Suggested items',
				items: vegetableItems.slice( 0, 3 )
			}
		];
		const menuItems = ref( initialMenuItems );
		const menuConfig = {
			boldLabel: true,
			visibleItemLimit: 6
		};

		/**
		 * On input, filter the menu items.
		 *
		 * @param {string} value
		 */
		function onInput( value ) {
			if ( value ) {
				menuItems.value = vegetableItems.filter( ( item ) =>
					item.label.includes( value )
				);
			} else {
				// When the input is cleared, show the suggestions again.
				menuItems.value = initialMenuItems;
			}
		}

		return {
			chips,
			selection,
			menuItems,
			menuConfig,
			onInput
		};
	}
} );
</script>

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

• No results found.

NPM

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Selected value: {{ selection }}
		</p>

		<cdx-multiselect-lookup
			v-model:input-chips="chips"
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			aria-label="MultiselectLookup with initial selection demo"
			@input="onInput"
		>
			<template #no-results>
				No results found.
			</template>
		</cdx-multiselect-lookup>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxMultiselectLookup } from '@wikimedia/codex';
import vegetableItems from '../../lookup/examples/data.json';

export default defineComponent( {
	name: 'MultiselectLookupWithInitialSelection',
	components: { CdxMultiselectLookup },
	setup() {
		const chips = ref( [
			{ label: 'carrot', value: 'Q81' },
			{ label: 'eggplant', value: 'Q7540' }
		] );
		const selection = ref( [ 'Q81', 'Q7540' ] );
		const menuItems = ref( [] );

		const menuConfig = {
			boldLabel: true,
			visibleItemLimit: 6
		};

		/**
		 * On input, filter the menu items.
		 *
		 * @param {string} value
		 */
		function onInput( value ) {
			if ( value ) {
				menuItems.value = vegetableItems.filter( ( item ) =>
					item.label.includes( value )
				);
			} else {
				menuItems.value = [];
			}
		}

		return {
			chips,
			selection,
			menuItems,
			menuConfig,
			onInput
		};
	}
} );
</script>

MediaWiki

<template>
	<div>
		<p class="cdx-docs-demo-text">
			Selected value: {{ selection }}
		</p>

		<cdx-multiselect-lookup
			v-model:input-chips="chips"
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			aria-label="MultiselectLookup with initial selection demo"
			@input="onInput"
		>
			<template #no-results>
				No results found.
			</template>
		</cdx-multiselect-lookup>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxMultiselectLookup } = require( '@wikimedia/codex' );
const vegetableItems = require( '../../lookup/examples/data.json' );

module.exports = defineComponent( {
	name: 'MultiselectLookupWithInitialSelection',
	components: { CdxMultiselectLookup },
	setup() {
		const chips = ref( [
			{ label: 'carrot', value: 'Q81' },
			{ label: 'eggplant', value: 'Q7540' }
		] );
		const selection = ref( [ 'Q81', 'Q7540' ] );
		const menuItems = ref( [] );

		const menuConfig = {
			boldLabel: true,
			visibleItemLimit: 6
		};

		/**
		 * On input, filter the menu items.
		 *
		 * @param {string} value
		 */
		function onInput( value ) {
			if ( value ) {
				menuItems.value = vegetableItems.filter( ( item ) =>
					item.label.includes( value )
				);
			} else {
				menuItems.value = [];
			}
		}

		return {
			chips,
			selection,
			menuItems,
			menuConfig,
			onInput
		};
	}
} );
</script>

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.

Namespaces Filter results by namespace

• No matching namespaces.

NPM

<template>
	<form class="cdx-docs-multiselect-lookup-form">
		<cdx-field :status="status" :messages="messages">
			<cdx-multiselect-lookup
				v-model:input-chips="chips"
				v-model:selected="selection"
				v-model:input-value="inputValue"
				:menu-items="menuItems"
				:menu-config="menuConfig"
				placeholder="Add a namespace..."
				@input="onInput"
				@update:selected="onSelection"
				@blur="validateInstantly"
				@keydown.enter="validateInstantly"
			>
				<template #no-results>
					No matching namespaces.
				</template>
			</cdx-multiselect-lookup>
			<template #label>
				Namespaces
			</template>
			<template #description>
				Filter results by namespace
			</template>
		</cdx-field>
		<cdx-button
			class="cdx-docs-multiselect-lookup-form__submit"
			action="progressive"
			weight="primary"
			type="submit"
			@click.prevent="onSubmit"
		>
			Submit
		</cdx-button>
	</form>
</template>

<script>
import { defineComponent, onMounted, ref, nextTick } from 'vue';
import { CdxField, CdxMultiselectLookup, CdxButton } from '@wikimedia/codex';

export default defineComponent( {
	name: 'MultiselectLookupField',
	components: {
		CdxField, CdxMultiselectLookup, CdxButton
	},
	setup() {
		const chips = ref( [] );
		const selection = ref( [] );
		const inputValue = ref( '' );

		const namespaces = ref( [] );
		const menuItems = ref( [] );

		const menuConfig = {
			visibleItemLimit: 6
		};

		const status = ref( 'default' );

		const messages = {
			warning: 'This entry is invalid. Please select an option from the menu.',
			error: 'This entry is invalid. Please select an option from the menu.'
		};

		/**
		 * Maybe set a warning message when the user moves out of the field or hits enter.
		 */
		function validateInstantly() {
			// Await nextTick in case the user has selected a menu item via the Enter key - this
			// will ensure the selection ref has been updated.
			nextTick( () => {
				// Set warning status if there's input. This might happen if a user types something
				// but doesn't select an item from the menu.
				status.value = inputValue.value.length > 0 ? 'warning' : 'default';
			} );
		}

		/**
		 * Maybe set an error message on submit.
		 */
		function onSubmit() {
			// Set an error message if there's input left in the field, or if there's no selection.
			if ( inputValue.value.length > 0 || selection.value.length === 0 ) {
				status.value = 'error';
			} else {
				status.value = 'default';
				// eslint-disable-next-line no-alert
				alert( 'Validation successful!' );
			}
		}

		/**
		 * Clear warning or error after a selection is made.
		 */
		function onSelection() {
			if ( selection.value !== null ) {
				status.value = 'default';
			}
		}

		/**
		 * Handle lookup input.
		 *
		 * @param {string} value The new input value
		 */
		function onInput( value ) {
			// Reset menu items if the input was cleared.
			if ( !value ) {
				menuItems.value = namespaces.value;
				return;
			}

			// Make sure this data is still relevant first.
			if ( inputValue.value !== value ) {
				return;
			}

			// Update menuItems.
			menuItems.value = namespaces.value.filter( ( namespace ) => {
				return namespace.label.includes( value );
			} );
		}

		/**
		 * Get a list of namespaces from English Wikipedia.
		 *
		 * @return {Promise}
		 */
		function getNamespaces() {
			const params = new URLSearchParams( {
				origin: '*',
				action: 'query',
				meta: 'siteinfo',
				siprop: 'namespaces',
				format: 'json',
				language: 'en'
			} );
			return fetch( `https://en.wikipedia.org/w/api.php?${ params.toString() }` )
				.then( ( response ) => response.json() );
		}

		function formatData( namespaceData ) {
			const formattedData = [];
			for ( const namespaceId of Object.keys( namespaceData ) ) {
				if ( 'canonical' in namespaceData[ namespaceId ] ) {
					formattedData.push( {
						value: namespaceId,
						label: namespaceData[ namespaceId ].canonical
					} );
				}
			}
			return formattedData;
		}

		onMounted( () => {
			getNamespaces()
				.then( ( data ) => {
					// Store formatted namespaces.
					namespaces.value = formatData( data.query.namespaces );
					// Set initial menu items.
					menuItems.value = namespaces.value;
				} );
		} );

		return {
			chips,
			selection,
			inputValue,
			menuItems,
			menuConfig,
			status,
			messages,
			validateInstantly,
			onSubmit,
			onSelection,
			onInput
		};
	}
} );
</script>

<style lang="less">
@import ( reference ) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';

.cdx-docs-multiselect-lookup-form {
	&__submit {
		margin-top: @spacing-100;
	}
}
</style>

MediaWiki

<template>
	<form class="cdx-docs-multiselect-lookup-form">
		<cdx-field :status="status" :messages="messages">
			<cdx-multiselect-lookup
				v-model:input-chips="chips"
				v-model:selected="selection"
				v-model:input-value="inputValue"
				:menu-items="menuItems"
				:menu-config="menuConfig"
				placeholder="Add a namespace..."
				@input="onInput"
				@update:selected="onSelection"
				@blur="validateInstantly"
				@keydown.enter="validateInstantly"
			>
				<template #no-results>
					No matching namespaces.
				</template>
			</cdx-multiselect-lookup>
			<template #label>
				Namespaces
			</template>
			<template #description>
				Filter results by namespace
			</template>
		</cdx-field>
		<cdx-button
			class="cdx-docs-multiselect-lookup-form__submit"
			action="progressive"
			weight="primary"
			type="submit"
			@click.prevent="onSubmit"
		>
			Submit
		</cdx-button>
	</form>
</template>

<script>
const { defineComponent, onMounted, ref, nextTick } = require( 'vue' );
const { CdxField, CdxMultiselectLookup, CdxButton } = require( '@wikimedia/codex' );

module.exports = defineComponent( {
	name: 'MultiselectLookupField',
	components: {
		CdxField, CdxMultiselectLookup, CdxButton
	},
	setup() {
		const chips = ref( [] );
		const selection = ref( [] );
		const inputValue = ref( '' );

		const namespaces = ref( [] );
		const menuItems = ref( [] );

		const menuConfig = {
			visibleItemLimit: 6
		};

		const status = ref( 'default' );

		const messages = {
			warning: 'This entry is invalid. Please select an option from the menu.',
			error: 'This entry is invalid. Please select an option from the menu.'
		};

		/**
		 * Maybe set a warning message when the user moves out of the field or hits enter.
		 */
		function validateInstantly() {
			// Await nextTick in case the user has selected a menu item via the Enter key - this
			// will ensure the selection ref has been updated.
			nextTick( () => {
				// Set warning status if there's input. This might happen if a user types something
				// but doesn't select an item from the menu.
				status.value = inputValue.value.length > 0 ? 'warning' : 'default';
			} );
		}

		/**
		 * Maybe set an error message on submit.
		 */
		function onSubmit() {
			// Set an error message if there's input left in the field, or if there's no selection.
			if ( inputValue.value.length > 0 || selection.value.length === 0 ) {
				status.value = 'error';
			} else {
				status.value = 'default';
				// eslint-disable-next-line no-alert
				alert( 'Validation successful!' );
			}
		}

		/**
		 * Clear warning or error after a selection is made.
		 */
		function onSelection() {
			if ( selection.value !== null ) {
				status.value = 'default';
			}
		}

		/**
		 * Handle lookup input.
		 *
		 * @param {string} value The new input value
		 */
		function onInput( value ) {
			// Reset menu items if the input was cleared.
			if ( !value ) {
				menuItems.value = namespaces.value;
				return;
			}

			// Make sure this data is still relevant first.
			if ( inputValue.value !== value ) {
				return;
			}

			// Update menuItems.
			menuItems.value = namespaces.value.filter( ( namespace ) => {
				return namespace.label.includes( value );
			} );
		}

		/**
		 * Get a list of namespaces from English Wikipedia.
		 *
		 * @return {Promise}
		 */
		function getNamespaces() {
			const params = new URLSearchParams( {
				origin: '*',
				action: 'query',
				meta: 'siteinfo',
				siprop: 'namespaces',
				format: 'json',
				language: 'en'
			} );
			return fetch( `https://en.wikipedia.org/w/api.php?${ params.toString() }` )
				.then( ( response ) => response.json() );
		}

		function formatData( namespaceData ) {
			const formattedData = [];
			for ( const namespaceId of Object.keys( namespaceData ) ) {
				if ( 'canonical' in namespaceData[ namespaceId ] ) {
					formattedData.push( {
						value: namespaceId,
						label: namespaceData[ namespaceId ].canonical
					} );
				}
			}
			return formattedData;
		}

		onMounted( () => {
			getNamespaces()
				.then( ( data ) => {
					// Store formatted namespaces.
					namespaces.value = formatData( data.query.namespaces );
					// Set initial menu items.
					menuItems.value = namespaces.value;
				} );
		} );

		return {
			chips,
			selection,
			inputValue,
			menuItems,
			menuConfig,
			status,
			messages,
			validateInstantly,
			onSubmit,
			onSelection,
			onInput
		};
	}
} );
</script>

<style lang="less">
@import 'mediawiki.skin.variables.less';

.cdx-docs-multiselect-lookup-form {
	&__submit {
		margin-top: @spacing-100;
	}
}
</style>

Other features

The MultiselectLookup component has an internal Menu and ChipInput. You can use the following features from those components in the MultiselectLookup component:

• Custom menu item display
• Menu groups

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