Lookup

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

Guidelines

When to use 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.

Specifications

Lookup includes the following elements:

1. 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.
2. Dropdown menu
   Suggested results are displayed via the Menu component.

Component limitations

Since the Lookup component uses a TextInput, its base min-width is set to size-1600 token (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. If the text entered in the input exceeds the available space, it will overflow horizontally.

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.

Clearable, with start icon

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

With custom menu item display

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

With initial suggestions

When the input field is focused, an initial list of suggestions may appear within the menu. When typing within the input field, these suggestions disappear, and the menu showcases a list of items matching the typed value. It is advisable to include a minimum of 2 suggested items and ideally limit the maximum to 4 or 5 items.

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.

Lookup within a form field

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

Interaction states

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

1. Default
2. Hover
3. Focus
4. Active
5. Filled
6. Filled active (with a menu item selected)
7. Error
8. Error hover
9. Disabled

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 Lookup is included within a Field.

Best practices

Consider the following recommendations when using Lookups.

Do:

• Wrap the Lookup within the Field component to incorporate features such as labels, descriptions, help text, or inline validation messages.
• Automatically display an inline warning message if the entered text doesn't match any item from the Lookup's menu, and show an error after form submission.

Don't:

• Use an inline success message to confirm a selection from the Lookup menu since it’s unnecessary.

Keyboard navigation

Key	Function
Down arrow	When the focus is placed on the Lookup, it opens the menu. When the menu is open, pressing it navigates through menu options. If pressed at the last visible option, it scrolls to the next "hidden" menu item.
Up arrow	When the focus is placed on the Lookup, it opens the menu. When the menu is open, it navigates through menu options.
Esc	When the menu is open, it closes the menu.
Enter	It opens the menu when the focus is placed on the Lookup. If the menu is open, it closes the menu. If the focus is placed in any of the options within the menu, the focused option is selected.

Demos

Configurable

• No results found.

<cdx-lookup />

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

Basic usage

The Lookup component emits an event on input. The parent component should react by computing or fetching menu items, then providing those items to the Lookup component for display by updating the menu-items prop. The user can then select an item from the menu.

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. See the Vue usage tables for more information.

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:

• No results found.

NPM

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

		<cdx-lookup
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			placeholder="Start typing a vegetable name"
			aria-label="Lookup basic demo"
			@input="onInput"
		>
			<template #no-results>
				No results found.
			</template>
		</cdx-lookup>
	</div>
</template>

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

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

		const menuConfig = {
			boldLabel: true
		};

		/**
		 * Filter items on input.
		 *
		 * @param {string} value
		 */
		function onInput( value ) {
			if ( value ) {
				menuItems.value = vegetableItems.filter( ( item ) =>
					item.label.includes( value )
				);
			}
		}

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

MediaWiki

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

		<cdx-lookup
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			placeholder="Start typing a vegetable name"
			aria-label="Lookup basic demo"
			@input="onInput"
		>
			<template #no-results>
				No results found.
			</template>
		</cdx-lookup>
	</div>
</template>

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

module.exports = defineComponent( {
	name: 'LookupBasic',
	components: { CdxLookup },
	setup() {
		const selection = ref( null );
		const menuItems = ref( [] );

		const menuConfig = {
			boldLabel: true
		};

		/**
		 * Filter items on input.
		 *
		 * @param {string} value
		 */
		function onInput( value ) {
			if ( value ) {
				menuItems.value = vegetableItems.filter( ( item ) =>
					item.label.includes( value )
				);
			}
		}

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

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

With fetched results

Often, Lookup is used to fetch results from an API endpoint. Parent components should react to the input or update:input-value 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 animation will display in the input.

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

MediaWiki

<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' );

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>

With suggestions

You can show a list of suggestions by passing 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.

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-lookup
			v-model:selected="selection"
			:menu-items="menuItems"
			:menu-config="menuConfig"
			aria-label="Lookup with suggested items demo"
			@input="onInput"
		>
			<template #no-results>
				No results found.
			</template>
		</cdx-lookup>
	</div>
</template>

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

export default defineComponent( {
	name: 'LookupWithSuggestions',
	components: { CdxLookup },
	setup() {
		const selection = ref( null );
		// Set up an array of initial menu items to show as suggestions.
		const initialMenuItems = [
			{
				label: 'Suggested items',
				value: 'suggestion',
				disabled: true
			},
			...vegetableItems.slice( 0, 3 )
		];
		const menuItems = ref( initialMenuItems );

		const menuConfig = {
			boldLabel: true
		};

		/**
		 * Filter items on input.
		 *
		 * @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 {
			selection,
			menuItems,
			menuConfig,
			onInput
		};
	}
} );
</script>

MediaWiki

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

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

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

module.exports = defineComponent( {
	name: 'LookupWithSuggestions',
	components: { CdxLookup },
	setup() {
		const selection = ref( null );
		// Set up an array of initial menu items to show as suggestions.
		const initialMenuItems = [
			{
				label: 'Suggested items',
				value: 'suggestion',
				disabled: true
			},
			...vegetableItems.slice( 0, 3 )
		];
		const menuItems = ref( initialMenuItems );

		const menuConfig = {
			boldLabel: true
		};

		/**
		 * Filter items on input.
		 *
		 * @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 {
			selection,
			menuItems,
			menuConfig,
			onInput
		};
	}
} );
</script>

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

With initial value

To set an initial selection and input value, do the following:

1. Set the selected prop to the value of the selected item.
2. Use the optional v-model:input-value prop to set the input value to the label of the selected item (or the value, if there is no label).

You can also use v-model:input-value to set an initial input value without an initial selection.

Selected value: Q81

• carrotroot vegetable, usually orange in color

NPM

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

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

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

export default defineComponent( {
	name: 'LookupWithInitialSelection',
	components: { CdxLookup },
	setup() {
		const selection = ref( 'Q81' );
		const inputValue = ref( 'carrot' );
		const menuItems = computed( () => vegetableItems.filter( ( item ) =>
			item.label.includes( inputValue.value )
		) );

		const menuConfig = {
			boldLabel: true
		};

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

MediaWiki

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

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

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

module.exports = defineComponent( {
	name: 'LookupWithInitialSelection',
	components: { CdxLookup },
	setup() {
		const selection = ref( 'Q81' );
		const inputValue = ref( 'carrot' );
		const menuItems = computed( () => vegetableItems.filter( ( item ) =>
			item.label.includes( inputValue.value )
		) );

		const menuConfig = {
			boldLabel: true
		};

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

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. Refer to the Field page for more information.

Item lookup Search Wikidata items

• No results found.

Start typing the name of a Wikidata item to see suggestions

NPM

<template>
	<form class="cdx-docs-lookup-form">
		<cdx-field :status="status" :messages="messages">
			<cdx-lookup
				v-model:selected="selection"
				v-model:input-value="inputValue"
				:menu-items="menuItems"
				:menu-config="menuConfig"
				@input="onInput"
				@load-more="onLoadMore"
				@update:selected="onSelection"
				@blur="validateInstantly"
				@keydown.enter="validateInstantly"
			>
				<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>
		<cdx-button
			class="cdx-docs-lookup-form__submit"
			action="progressive"
			weight="primary"
			type="submit"
			@click.prevent="onSubmit"
		>
			Submit
		</cdx-button>
	</form>
</template>

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

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

		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 but no selection. This might happen if a
				// user types something but doesn't select an item from the menu.
				status.value = inputValue.value.length > 0 && selection.value === null ?
					'warning' :
					'default';
			} );
		}

		/**
		 * Show error message on submit if nothing is selected.
		 */
		function onSubmit() {
			if ( selection.value === null ) {
				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';
			}
		}

		/**
		 * 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 ) {
			// 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 ( 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 );
				} );
		}

		const menuConfig = {
			visibleItemLimit: 6
		};

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

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

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

MediaWiki

<template>
	<form class="cdx-docs-lookup-form">
		<cdx-field :status="status" :messages="messages">
			<cdx-lookup
				v-model:selected="selection"
				v-model:input-value="inputValue"
				:menu-items="menuItems"
				:menu-config="menuConfig"
				@input="onInput"
				@load-more="onLoadMore"
				@update:selected="onSelection"
				@blur="validateInstantly"
				@keydown.enter="validateInstantly"
			>
				<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>
		<cdx-button
			class="cdx-docs-lookup-form__submit"
			action="progressive"
			weight="primary"
			type="submit"
			@click.prevent="onSubmit"
		>
			Submit
		</cdx-button>
	</form>
</template>

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

module.exports = defineComponent( {
	name: 'LookupField',
	components: { CdxLookup, CdxField, CdxButton },
	setup() {
		const selection = ref( null );
		const menuItems = ref( [] );
		const inputValue = ref( '' );

		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 but no selection. This might happen if a
				// user types something but doesn't select an item from the menu.
				status.value = inputValue.value.length > 0 && selection.value === null ?
					'warning' :
					'default';
			} );
		}

		/**
		 * Show error message on submit if nothing is selected.
		 */
		function onSubmit() {
			if ( selection.value === null ) {
				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';
			}
		}

		/**
		 * 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 ) {
			// 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 ( 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 );
				} );
		}

		const menuConfig = {
			visibleItemLimit: 6
		};

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

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

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

Other features

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

• Custom menu item display
• Start and end icons
• Clearable

Vue usage

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	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[]
inputValue	Current value of the input. This prop is optional and should only be used if you need to keep track of the input value for some reason (e.g. to set an initial value). Optionally provided by v-model:input-value binding in the parent component.	string|number	null
initialInputValue	Initial value of the text input. Non-reactive. @deprecated Use inputValue instead.	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	{}
status	status property of the TextInput component	ValidationStatusType	'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.
update:input-value	inputValue string|number - The new input value	When the input value changes. Only emitted if the inputValue prop is provided.
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.

<!-- Wrapper div. -->
<div class="cdx-text-input">
  <!-- Input element with CSS class and attributes. -->
  <input
    class="cdx-text-input__input"
    type="text"
    placeholder="Start typing a vegetable name..."
  />
</div>