Lookup

A Lookup is a predictive text input that presents a dropdown menu with suggestions based on the current input value.

Guidelines

Using lookups

Use the Lookup component to let users search through a dataset to choose a predefined value for a form field. This can be useful when there are many options the user can choose from, so they need to filter the items via a text query.

Avoid using Lookup to enable users to search for and navigate to content. Instead, use SearchInput or TypeaheadSearch.

Example of Codex Lookup.

Specifications

Specification of Lookup.

Lookup includes the following elements:

Input
A TextInput where the user types to look for the suggested results. This can optionally include a start icon, clear button, and placeholder text.
Dropdown menu
Suggested results are displayed via the Menu component.

Refer to the Lookup component in Codex Figma.

Types

An input field featuring an optional placeholder will enable users to initiate their search for suggested results. These suggestions will be displayed within a dropdown menu, and if the menu cannot fully accommodate the results, a scrollbar with the choice of infinite scroll can be included.

Example of Lookup with a custom placeholder.

Clearable, with start icon

An optional start icon and clear button could appear within the input field.

Custom content and formats can be applied to change the appearance of menu items according to your needs.

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.

Example of a Lookup with no results found.

Lookup within a form field

A Lookup can be wrapped within a Field to include features like label, description, help text, or validation messages.

Example of Lookup within a Field component.

Interaction states

Interaction can take place within both the input and the displayed menu:

Interaction states of the Lookup component: default, hover, focus, active, filled, and filled active where a menu item selected is displayed.

Default
Hover
Focus
Active
Filled
Filled active (with a menu item selected)

Demos

Default

The Lookup component will emit input events on input, which the parent component should react to by computing or fetching menu items, then providing those items to the Lookup component for display by updating the menu-items prop.

Items are displayed via the MenuItem component—see 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:

Name	Value
View
Reading direction	Left to right (LTR) Right to left (RTL)

The menu-item slot can be used to set up custom menu item content and formatting.

With "no results" content

A non-interactive "no results" message can be displayed via the no-results slot. If populated, this slot will automatically display when there are zero menu items.

With fetched results and infinite scroll

Often, Lookup is used to fetch results from an API endpoint. Parent components should react to the input event emitted by Lookup to search for results, then pass back to the Lookup either an array of results to display as menu items or an empty array if there are no results. Between those two events, a pending state animation will display in the input.

Scrolling is enabled by setting the visibleItemLimit property of the menuConfig prop.

With scrolling enabled, 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.

NPMMediaWiki

vue

<template>
	<div>
		<cdx-lookup
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			aria-label="Lookup with fetched results demo"
			@input="onInput"
			@load-more="onLoadMore"
		>
			<template #no-results>
				No results found.
			</template>
		</cdx-lookup>
	</div>
</template>

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

export default defineComponent( {
	name: 'LookupWithFetch',
	components: { CdxLookup },
	setup() {
		const selection = ref( null );
		const menuItems = ref( [] );
		const currentSearchTerm = ref( '' );

		/**
		 * 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
		 */
		function onInput( value ) {
			// Internally track the current search term.
			currentSearchTerm.value = value;

			// Do nothing if we have no input.
			if ( !value ) {
				menuItems.value = [];
				return;
			}

			fetchResults( value )
				.then( ( data ) => {
					// Make sure this data is still relevant first.
					if ( currentSearchTerm.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 ( !currentSearchTerm.value ) {
				return;
			}

			fetchResults( currentSearchTerm.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 );
				} );
		}

		const menuConfig = {
			visibleItemLimit: 6
		};

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

vue

<template>
	<div>
		<cdx-lookup
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			aria-label="Lookup with fetched results demo"
			@input="onInput"
			@load-more="onLoadMore"
		>
			<template #no-results>
				No results found.
			</template>
		</cdx-lookup>
	</div>
</template>

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

// @vue/component
module.exports = defineComponent( {
	name: 'LookupWithFetch',
	components: { CdxLookup },
	setup() {
		const selection = ref( null );
		const menuItems = ref( [] );
		const currentSearchTerm = ref( '' );

		/**
		 * 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
		 */
		function onInput( value ) {
			// Internally track the current search term.
			currentSearchTerm.value = value;

			// Do nothing if we have no input.
			if ( !value ) {
				menuItems.value = [];
				return;
			}

			fetchResults( value )
				.then( ( data ) => {
					// Make sure this data is still relevant first.
					if ( currentSearchTerm.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 ( !currentSearchTerm.value ) {
				return;
			}

			fetchResults( currentSearchTerm.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 );
				} );
		}

		const menuConfig = {
			visibleItemLimit: 6
		};

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

Clearable, with start icon

Props of the TextInput component can be bound to Lookup and will be passed down to the TextInput component inside of it, so you can take advantage of features like the "clear" button and icons.

With placeholder

Attributes (except for class) will fall through to the input element, so you can set things like placeholder on the Lookup component and they'll be applied to the input.

Form field

A Lookup can be wrapped in the Field component to add features like a semantic label, description and help text, validation messages, and more. See the Field page for more information.

Item lookup Search Wikidata items

Start typing the name of a Wikidata item to see suggestions

NPMMediaWiki

vue

<template>
	<cdx-field>
		<cdx-lookup
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			@input="onInput"
			@load-more="onLoadMore"
		>
			<template #no-results>
				No results found.
			</template>
		</cdx-lookup>
		<template #label>
			Item lookup
		</template>
		<template #description>
			Search Wikidata items
		</template>
		<template #help-text>
			Start typing the name of a Wikidata item to see suggestions
		</template>
	</cdx-field>
</template>

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

export default defineComponent( {
	name: 'LookupField',
	components: { CdxLookup, CdxField },
	setup() {
		const selection = ref( null );
		const menuItems = ref( [] );
		const currentSearchTerm = ref( '' );

		/**
		 * 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
		 */
		function onInput( value ) {
			// Internally track the current search term.
			currentSearchTerm.value = value;

			// Do nothing if we have no input.
			if ( !value ) {
				menuItems.value = [];
				return;
			}

			fetchResults( value )
				.then( ( data ) => {
					// Make sure this data is still relevant first.
					if ( currentSearchTerm.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 ( !currentSearchTerm.value ) {
				return;
			}

			fetchResults( currentSearchTerm.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 );
				} );
		}

		const menuConfig = {
			visibleItemLimit: 6
		};

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

vue

<template>
	<cdx-field>
		<cdx-lookup
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			@input="onInput"
			@load-more="onLoadMore"
		>
			<template #no-results>
				No results found.
			</template>
		</cdx-lookup>
		<template #label>
			Item lookup
		</template>
		<template #description>
			Search Wikidata items
		</template>
		<template #help-text>
			Start typing the name of a Wikidata item to see suggestions
		</template>
	</cdx-field>
</template>

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

// @vue/component
module.exports = defineComponent( {
	name: 'LookupField',
	components: { CdxLookup, CdxField },
	setup() {
		const selection = ref( null );
		const menuItems = ref( [] );
		const currentSearchTerm = ref( '' );

		/**
		 * 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
		 */
		function onInput( value ) {
			// Internally track the current search term.
			currentSearchTerm.value = value;

			// Do nothing if we have no input.
			if ( !value ) {
				menuItems.value = [];
				return;
			}

			fetchResults( value )
				.then( ( data ) => {
					// Make sure this data is still relevant first.
					if ( currentSearchTerm.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 ( !currentSearchTerm.value ) {
				return;
			}

			fetchResults( currentSearchTerm.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 );
				} );
		}

		const menuConfig = {
			visibleItemLimit: 6
		};

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

Vue usage

Typical use of this component will involve listening for input events, fetching or otherwise computing menu items, then passing those menu items back to the Lookup for display.

TextInput props apply

This component contains a TextInput component. You can bind TextInput props to this component and they will be passed to the TextInput within.

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	Values	Default
`selected`^(required)	Value of the current selection. Must be bound with `v-model:selected`. The property should be initialized to `null` rather than using a falsy value.	`string\|number\|null`	-
`menuItems`^(required)	Menu items.	`MenuItemData[]`	-
`initialInputValue`	Initial value of the text input.	`string\|number`	-	`''`
`disabled`	Whether the entire component is disabled.	`boolean`	-	`false`
`menuConfig`	Configuration for various menu features. All properties default to false. See the MenuConfig type.	`MenuConfig`	-	`() => { return {} as MenuConfig; }`
`status`	`status` property of the TextInput component	`ValidationStatusType`	`'default'`, `'error'`	`'default'`

Events

Event name	Properties	Description
`change`	event `Event`	When an input value change is committed by the user (e.g. on blur)
`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:selected`	selected `string\|number\|null` - The new selected value	When the selected value changes.
`input`	value `string\|number` - The new value	When the text input value changes.
`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.

CSS-only version

Markup structure

There is no true CSS-only version of the Lookup component. However, a CSS-only TextInput component can be used instead, since it has visual parity with the Lookup component with its menu collapsed. For example, you could display a CSS-only TextInput on page load while a Vue app loads, then replace it with the Vue Lookup component once the Vue app has mounted.

The example below is a simple text input with a placeholder, but icons and different states are supported—see the TextInput docs for more information.

Lookup

Guidelines

Using lookups

Specifications

Types

Clearable, with start icon

With custom menu item display

No results

Lookup within a form field

Interaction states

Demos

Default

With custom menu item display

With "no results" content

With fetched results and infinite scroll

Clearable, with start icon

With placeholder

Form field

Vue usage

Props

Events

Slots

CSS-only version

Markup structure

Lookup ​

Guidelines ​

Using lookups ​

Specifications ​

Types ​

Clearable, with start icon ​

With custom menu item display ​

No results ​

Lookup within a form field ​

Interaction states ​

Demos ​

Default ​

With custom menu item display ​

With "no results" content ​

With fetched results and infinite scroll ​

Clearable, with start icon ​

With placeholder ​

Form field ​

Vue usage ​

Props ​

Events ​

Slots ​

CSS-only version ​

Markup structure ​

Lookup

Guidelines

Using lookups

Specifications

Types

Clearable, with start icon

With custom menu item display

No results

Lookup within a form field

Interaction states

Demos

Default

With custom menu item display

With "no results" content

With fetched results and infinite scroll

Clearable, with start icon

With placeholder

Form field

Vue usage

Props

Events

Slots

CSS-only version

Markup structure