TypeaheadSearch

TypeaheadSearch is a search input that provides a menu of options based on the current search query. It is meant to help users search for and navigate to content.

Guidelines

Using TypeaheadSearch

TypeaheadSearch consists of a search input and a submit button. As users type, predictive search results are displayed in a menu. Additionally, there's a final option at the end of the search results list, enabling users to navigate to the search page.

Use the TypeaheadSearch component when you need a predictive list of options in a menu that updates as users type within the input field. Avoid using TypeaheadSearch if your goal is to enable users to perform text-based searches to find specific content, such as locating results on a page. In this case use the SearchInput component instead.

Specifications

TypeaheadSearch may include the following elements:

Input
A search input where users can type their searches. The input features the 'search' icon for clarity and should also include a placeholder to clarify its purpose.
Button (optional)
The input can be accompanied with a button, in order to trigger the search action. It's crucial not to customize the label of the search button: consistently employ the term "Search" or its appropriate translation. Additionally, avoid using long text within this button.
Menu
When the user types within the input, a menu component with results is displayed. By default, menu items will feature a label and an optional description. Thumbnails can also be included.
Footer
The final menu item at the end of the search results menu list allows users to navigate to the search page.

Types

As with SearchInput, TypeaheadSearch can be categorized based on the visibility and type of button it contains:

Without button
The TypeaheadSearch can consist of the input field alone or include the decorative icon. In this scenario, using the icon is suggested to emphasize that the input serves as a search input, distinguishing it from a simple text input.
With text button
The TypeaheadSearch also has the option to feature a text button to initiate the search process.

Interaction states

TypeaheadSearch has the following visually separate states:

Default
Hover
Focus
Loading
Active with results
Active with no results

Demos

Search Wikipedia articles

This implementation of TypeaheadSearch fetches articles from English Wikipedia. Note that the input expands on focus via the autoExpandWidth prop, thumbnails are enabled via the showThumbnail prop, and the "search" button is added via the buttonLabel prop. Open the console to see emitted events.

NPMMediaWiki

vue

<template>
	<div>
		<cdx-typeahead-search
			id="typeahead-search-wikipedia"
			form-action="https://en.wikipedia.org/w/index.php"
			button-label="Search"
			search-results-label="Search results"
			:search-results="searchResults"
			:search-footer-url="searchFooterUrl"
			:show-thumbnail="true"
			:highlight-query="true"
			:auto-expand-width="true"
			placeholder="Search Wikipedia"
			@input="onInput"
			@search-result-click="onSearchResultClick"
			@submit="onSubmit"
		>
			<template #default>
				<input
					type="hidden"
					name="language"
					value="en"
				>
				<input
					type="hidden"
					name="title"
					value="Special:Search"
				>
			</template>
			<template #search-footer-text="{ searchQuery }">
				Search Wikipedia for pages containing
				<strong class="cdx-typeahead-search__search-footer__query">
					{{ searchQuery }}
				</strong>
			</template>
		</cdx-typeahead-search>
	</div>
</template>

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

export default defineComponent( {
	name: 'TypeaheadSearchWikipedia',
	components: { CdxTypeaheadSearch },
	setup() {
		const searchResults = ref( [] );
		const searchFooterUrl = ref( '' );
		const currentSearchTerm = ref( '' );

		function onInput( value ) {
			// eslint-disable-next-line no-console
			console.log( 'input event emitted with value:', value );

			// Internally track the current search term.
			currentSearchTerm.value = value;

			// Unset search results and the search footer URL if there is no value.
			if ( !value || value === '' ) {
				searchResults.value = [];
				searchFooterUrl.value = '';
				return;
			}

			/**
			 * Format search results for consumption by TypeaheadSearch.
			 *
			 * @param pages
			 * @return
			 */
			function adaptApiResponse( pages ) {
				return pages.map( ( { id, key, title, description, thumbnail } ) => ( {
					label: title,
					value: id,
					description: description,
					url: `https://en.wikipedia.org/wiki/${encodeURIComponent( key )}`,
					thumbnail: thumbnail ? {
						url: thumbnail.url,
						width: thumbnail.width,
						height: thumbnail.height
					} : undefined
				} ) );
			}

			fetch(
				`https://en.wikipedia.org/w/rest.php/v1/search/title?q=${encodeURIComponent( value )}&limit=10&`
			).then( ( resp ) => resp.json() )
				.then( ( data ) => {
					// Make sure this data is still relevant first.
					if ( currentSearchTerm.value === value ) {
						// If there are results, format them into an array of
						// SearchResults to be passed into TypeaheadSearch for
						// display as a menu of suggestions.
						searchResults.value = data.pages && data.pages.length > 0 ?
							adaptApiResponse( data.pages ) :
							[];

						// Set the search footer URL to a link to the search
						// page for the current search query.
						searchFooterUrl.value = `https://en.wikipedia.org/w/index.php?title=Special%3ASearch&fulltext=1&search=${encodeURIComponent( value )}`;

					}
				} ).catch( () => {
					// On error, reset search results and search footer URL.
					searchResults.value = [];
					searchFooterUrl.value = '';
				} );
		}

		function onSearchResultClick( value ) {
			// eslint-disable-next-line no-console
			console.log( 'search-result-click event emitted with value:', value );
		}

		function onSubmit( value ) {
			// eslint-disable-next-line no-console
			console.log( 'submit event emitted with value:', value );
		}

		return {
			searchResults,
			searchFooterUrl,
			onInput,
			onSearchResultClick,
			onSubmit
		};
	}
} );
</script>

vue

<template>
	<div>
		<cdx-typeahead-search
			id="typeahead-search-wikipedia"
			form-action="https://en.wikipedia.org/w/index.php"
			button-label="Search"
			search-results-label="Search results"
			:search-results="searchResults"
			:search-footer-url="searchFooterUrl"
			:show-thumbnail="true"
			:highlight-query="true"
			:auto-expand-width="true"
			placeholder="Search Wikipedia"
			@input="onInput"
			@search-result-click="onSearchResultClick"
			@submit="onSubmit"
		>
			<template #default>
				<input
					type="hidden"
					name="language"
					value="en"
				>
				<input
					type="hidden"
					name="title"
					value="Special:Search"
				>
			</template>
			<template #search-footer-text="{ searchQuery }">
				Search Wikipedia for pages containing
				<strong class="cdx-typeahead-search__search-footer__query">
					{{ searchQuery }}
				</strong>
			</template>
		</cdx-typeahead-search>
	</div>
</template>

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

// @vue/component
module.exports = defineComponent( {
	name: 'TypeaheadSearchWikipedia',
	components: { CdxTypeaheadSearch },
	setup() {
		const searchResults = ref( [] );
		const searchFooterUrl = ref( '' );
		const currentSearchTerm = ref( '' );

		function onInput( value ) {
			// eslint-disable-next-line no-console
			console.log( 'input event emitted with value:', value );

			// Internally track the current search term.
			currentSearchTerm.value = value;

			// Unset search results and the search footer URL if there is no value.
			if ( !value || value === '' ) {
				searchResults.value = [];
				searchFooterUrl.value = '';
				return;
			}

			/**
			 * Format search results for consumption by TypeaheadSearch.
			 *
			 * @param pages
			 * @return
			 */
			function adaptApiResponse( pages ) {
				return pages.map( ( { id, key, title, description, thumbnail } ) => ( {
					label: title,
					value: id,
					description: description,
					url: `https://en.wikipedia.org/wiki/${encodeURIComponent( key )}`,
					thumbnail: thumbnail ? {
						url: thumbnail.url,
						width: thumbnail.width,
						height: thumbnail.height
					} : undefined
				} ) );
			}

			fetch(
				`https://en.wikipedia.org/w/rest.php/v1/search/title?q=${encodeURIComponent( value )}&limit=10&`
			).then( ( resp ) => resp.json() )
				.then( ( data ) => {
					// Make sure this data is still relevant first.
					if ( currentSearchTerm.value === value ) {
						// If there are results, format them into an array of
						// SearchResults to be passed into TypeaheadSearch for
						// display as a menu of suggestions.
						searchResults.value = data.pages && data.pages.length > 0 ?
							adaptApiResponse( data.pages ) :
							[];

						// Set the search footer URL to a link to the search
						// page for the current search query.
						searchFooterUrl.value = `https://en.wikipedia.org/w/index.php?title=Special%3ASearch&fulltext=1&search=${encodeURIComponent( value )}`;

					}
				} ).catch( () => {
					// On error, reset search results and search footer URL.
					searchResults.value = [];
					searchFooterUrl.value = '';
				} );
		}

		function onSearchResultClick( value ) {
			// eslint-disable-next-line no-console
			console.log( 'search-result-click event emitted with value:', value );
		}

		function onSubmit( value ) {
			// eslint-disable-next-line no-console
			console.log( 'submit event emitted with value:', value );
		}

		return {
			searchResults,
			searchFooterUrl,
			onInput,
			onSearchResultClick,
			onSubmit
		};
	}
} );
</script>

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

Search Wikidata items

In this example, results are fetched from Wikidata. Thumbnails are disabled, and the input doesn't expand on focus. There is no button, because the buttonLabel prop is not set. Open the console to see emitted events.

NPMMediaWiki

vue

<template>
	<div>
		<cdx-typeahead-search
			id="typeahead-search-wikidata"
			form-action="https://www.wikidata.org/w/index.php"
			search-results-label="Search results"
			:search-results="searchResults"
			:search-footer-url="searchFooterUrl"
			:highlight-query="true"
			:visible-item-limit="5"
			placeholder="Search Wikidata"
			@input="onInput"
			@search-result-click="onSearchResultClick"
			@submit="onSubmit"
			@load-more="onLoadMore"
		>
			<template #default>
				<input
					type="hidden"
					name="language"
					value="en"
				>
				<input
					type="hidden"
					name="title"
					value="Special:Search"
				>
			</template>
			<template #search-footer-text="{ searchQuery }">
				Search Wikidata for pages containing
				<strong class="cdx-typeahead-search__search-footer__query">
					{{ searchQuery }}
				</strong>
			</template>
		</cdx-typeahead-search>
	</div>
</template>

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

export default defineComponent( {
	name: 'TypeaheadSearchWikidata',
	components: { CdxTypeaheadSearch },
	setup() {
		const searchResults = ref( [] );
		const searchFooterUrl = ref( '' );
		const currentSearchTerm = ref( '' );

		function fetchResults( searchTerm, offset ) {
			const params = new URLSearchParams( {
				origin: '*',
				action: 'wbsearchentities',
				format: 'json',
				limit: '10',
				props: 'url',
				language: 'en',
				uselang: 'en',
				type: 'item',
				search: searchTerm
			} );
			if ( offset ) {
				params.set( 'continue', `${offset}` );
			}
			return fetch( `https://www.wikidata.org/w/api.php?${params.toString()}` )
				.then( ( response ) => response.json() );
		}

		/**
		 * Format search results for consumption by TypeaheadSearch.
		 *
		 * @param pages
		 * @return
		 */
		function adaptApiResponse( pages ) {
			return pages.map( ( { id, label, url, match, description, display = {} } ) => ( {
				value: id,
				label,
				match: match.type === 'alias' ? `(${match.text})` : '',
				description,
				url,
				language: {
					label: display && display.label && display.label.language,
					match: match.type === 'alias' ? match.language : undefined,
					description: display && display.description && display.description.language
				}
			} ) );
		}

		function onInput( value ) {
			// eslint-disable-next-line no-console
			console.log( 'input event emitted with value:', value );

			// Internally track the current search term.
			currentSearchTerm.value = value;

			// Unset search results and the search footer URL if there is no value.
			if ( !value || value === '' ) {
				searchResults.value = [];
				searchFooterUrl.value = '';
				return;
			}

			fetchResults( value ).then( ( data ) => {
				// Make sure this data is still relevant first.
				if ( currentSearchTerm.value === value ) {
					// If there are results, format them into an array of
					// SearchResults to be passed into TypeaheadSearch for
					// display as a menu of search results.
					searchResults.value = data.search && data.search.length > 0 ?
						adaptApiResponse( data.search ) :
						[];

					// Set the search footer URL to a link to the search
					// page for the current search query.
					searchFooterUrl.value = `https://www.wikidata.org/w/index.php?search=${encodeURIComponent( value )}&title=Special%3ASearch&fulltext=1`;
				}
			} ).catch( () => {
				// On error, reset search results and search footer URL.
				searchResults.value = [];
				searchFooterUrl.value = '';
			} );
		}

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

		function onLoadMore() {
			// eslint-disable-next-line no-console
			console.log( 'load-more event emitted' );

			if ( !currentSearchTerm.value ) {
				return;
			}

			fetchResults( currentSearchTerm.value, searchResults.value.length ).then( ( data ) => {
				const results = data.search && data.search.length > 0 ?
					adaptApiResponse( data.search ) :
					[];

				const deduplicatedResults = deduplicateResults( results );
				searchResults.value.push( ...deduplicatedResults );
			} );
		}

		function onSearchResultClick( value ) {
			// eslint-disable-next-line no-console
			console.log( 'search-result-click event emitted with value:', value );
		}

		function onSubmit( value ) {
			// eslint-disable-next-line no-console
			console.log( 'submit event emitted with value:', value );
		}

		return {
			searchResults,
			searchFooterUrl,
			onInput,
			onLoadMore,
			onSearchResultClick,
			onSubmit
		};
	}
} );
</script>

vue

<template>
	<div>
		<cdx-typeahead-search
			id="typeahead-search-wikidata"
			form-action="https://www.wikidata.org/w/index.php"
			search-results-label="Search results"
			:search-results="searchResults"
			:search-footer-url="searchFooterUrl"
			:highlight-query="true"
			:visible-item-limit="5"
			placeholder="Search Wikidata"
			@input="onInput"
			@search-result-click="onSearchResultClick"
			@submit="onSubmit"
			@load-more="onLoadMore"
		>
			<template #default>
				<input
					type="hidden"
					name="language"
					value="en"
				>
				<input
					type="hidden"
					name="title"
					value="Special:Search"
				>
			</template>
			<template #search-footer-text="{ searchQuery }">
				Search Wikidata for pages containing
				<strong class="cdx-typeahead-search__search-footer__query">
					{{ searchQuery }}
				</strong>
			</template>
		</cdx-typeahead-search>
	</div>
</template>

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

// @vue/component
module.exports = defineComponent( {
	name: 'TypeaheadSearchWikidata',
	components: { CdxTypeaheadSearch },
	setup() {
		const searchResults = ref( [] );
		const searchFooterUrl = ref( '' );
		const currentSearchTerm = ref( '' );

		function fetchResults( searchTerm, offset ) {
			const params = new URLSearchParams( {
				origin: '*',
				action: 'wbsearchentities',
				format: 'json',
				limit: '10',
				props: 'url',
				language: 'en',
				uselang: 'en',
				type: 'item',
				search: searchTerm
			} );
			if ( offset ) {
				params.set( 'continue', `${offset}` );
			}
			return fetch( `https://www.wikidata.org/w/api.php?${params.toString()}` )
				.then( ( response ) => response.json() );
		}

		/**
		 * Format search results for consumption by TypeaheadSearch.
		 *
		 * @param pages
		 * @return
		 */
		function adaptApiResponse( pages ) {
			return pages.map( ( { id, label, url, match, description, display = {} } ) => ( {
				value: id,
				label,
				match: match.type === 'alias' ? `(${match.text})` : '',
				description,
				url,
				language: {
					label: display && display.label && display.label.language,
					match: match.type === 'alias' ? match.language : undefined,
					description: display && display.description && display.description.language
				}
			} ) );
		}

		function onInput( value ) {
			// eslint-disable-next-line no-console
			console.log( 'input event emitted with value:', value );

			// Internally track the current search term.
			currentSearchTerm.value = value;

			// Unset search results and the search footer URL if there is no value.
			if ( !value || value === '' ) {
				searchResults.value = [];
				searchFooterUrl.value = '';
				return;
			}

			fetchResults( value ).then( ( data ) => {
				// Make sure this data is still relevant first.
				if ( currentSearchTerm.value === value ) {
					// If there are results, format them into an array of
					// SearchResults to be passed into TypeaheadSearch for
					// display as a menu of search results.
					searchResults.value = data.search && data.search.length > 0 ?
						adaptApiResponse( data.search ) :
						[];

					// Set the search footer URL to a link to the search
					// page for the current search query.
					searchFooterUrl.value = `https://www.wikidata.org/w/index.php?search=${encodeURIComponent( value )}&title=Special%3ASearch&fulltext=1`;
				}
			} ).catch( () => {
				// On error, reset search results and search footer URL.
				searchResults.value = [];
				searchFooterUrl.value = '';
			} );
		}

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

		function onLoadMore() {
			// eslint-disable-next-line no-console
			console.log( 'load-more event emitted' );

			if ( !currentSearchTerm.value ) {
				return;
			}

			fetchResults( currentSearchTerm.value, searchResults.value.length ).then( ( data ) => {
				const results = data.search && data.search.length > 0 ?
					adaptApiResponse( data.search ) :
					[];

				const deduplicatedResults = deduplicateResults( results );
				searchResults.value.push( ...deduplicatedResults );
			} );
		}

		function onSearchResultClick( value ) {
			// eslint-disable-next-line no-console
			console.log( 'search-result-click event emitted with value:', value );
		}

		function onSubmit( value ) {
			// eslint-disable-next-line no-console
			console.log( 'submit event emitted with value:', value );
		}

		return {
			searchResults,
			searchFooterUrl,
			onInput,
			onLoadMore,
			onSearchResultClick,
			onSubmit
		};
	}
} );
</script>

With initial input value

The initialInputValue prop can be used to pass in the initial value of the TextInput. This is useful when replacing a server-rendered UI where the user may have started typing a search query, or for pre-populating the search term when a user navigates back to a page where they had previously entered one.

On mount, TypeaheadSearch will fetch search results for the initial input value if it's provided. After that, the input value is tracked internally and will be emitted up to the parent component when the value changes.

NPMMediaWiki

vue

<template>
	<div>
		<cdx-typeahead-search
			id="typeahead-search-default"
			form-action="https://en.wikipedia.org/w/index.php"
			button-label="Search"
			search-results-label="Search results"
			:initial-input-value="initialInputValue"
			:search-results="searchResults"
			:search-footer-url="searchFooterUrl"
			:show-thumbnail="true"
			:highlight-query="true"
			placeholder="Search Wikipedia"
			@input="onInput"
		>
			<template #search-footer-text="{ searchQuery }">
				Search Wikipedia for pages containing
				<strong class="cdx-typeahead-search__search-footer__query">
					{{ searchQuery }}
				</strong>
			</template>
		</cdx-typeahead-search>
	</div>
</template>

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

export default defineComponent( {
	name: 'TypeaheadSearchInitialValue',
	components: { CdxTypeaheadSearch },
	props: {
		/**
		 * For demo purposes, the initial input value "Color" has been passed in
		 * as a prop.
		 */
		initialInputValue: {
			type: String,
			default: ''
		}
	},
	setup() {
		const searchResults = ref( [] );
		const searchFooterUrl = ref( '' );
		const currentSearchTerm = ref( '' );

		function onInput( value ) {
			currentSearchTerm.value = value;

			if ( !value || value === '' ) {
				searchResults.value = [];
				searchFooterUrl.value = '';
				return;
			}

			/**
			 * Format search results for consumption by TypeaheadSearch.
			 *
			 * @param pages
			 * @return
			 */
			function adaptApiResponse( pages ) {
				return pages.map( ( { id, key, title, description, thumbnail } ) => ( {
					label: title,
					value: id,
					description: description,
					url: `https://en.wikipedia.org/wiki/${encodeURIComponent( key )}`,
					thumbnail: thumbnail ? {
						url: thumbnail.url,
						width: thumbnail.width,
						height: thumbnail.height
					} : undefined
				} ) );
			}

			fetch(
				`https://en.wikipedia.org/w/rest.php/v1/search/title?q=${encodeURIComponent( value )}&limit=10&`
			).then( ( resp ) => resp.json() )
				.then( ( data ) => {
					if ( currentSearchTerm.value === value ) {
						searchResults.value = data.pages && data.pages.length > 0 ?
							adaptApiResponse( data.pages ) :
							[];

						searchFooterUrl.value = `https://en.wikipedia.org/w/index.php?title=Special%3ASearch&fulltext=1&search=${encodeURIComponent( value )}`;

					}
				} ).catch( () => {
					searchResults.value = [];
					searchFooterUrl.value = '';
				} );
		}

		return {
			searchResults,
			searchFooterUrl,
			onInput
		};
	}
} );
</script>

vue

<template>
	<div>
		<cdx-typeahead-search
			id="typeahead-search-default"
			form-action="https://en.wikipedia.org/w/index.php"
			button-label="Search"
			search-results-label="Search results"
			:initial-input-value="initialInputValue"
			:search-results="searchResults"
			:search-footer-url="searchFooterUrl"
			:show-thumbnail="true"
			:highlight-query="true"
			placeholder="Search Wikipedia"
			@input="onInput"
		>
			<template #search-footer-text="{ searchQuery }">
				Search Wikipedia for pages containing
				<strong class="cdx-typeahead-search__search-footer__query">
					{{ searchQuery }}
				</strong>
			</template>
		</cdx-typeahead-search>
	</div>
</template>

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

// @vue/component
module.exports = defineComponent( {
	name: 'TypeaheadSearchInitialValue',
	components: { CdxTypeaheadSearch },
	props: {
		/**
		 * For demo purposes, the initial input value "Color" has been passed in
		 * as a prop.
		 */
		initialInputValue: {
			type: String,
			default: ''
		}
	},
	setup() {
		const searchResults = ref( [] );
		const searchFooterUrl = ref( '' );
		const currentSearchTerm = ref( '' );

		function onInput( value ) {
			currentSearchTerm.value = value;

			if ( !value || value === '' ) {
				searchResults.value = [];
				searchFooterUrl.value = '';
				return;
			}

			/**
			 * Format search results for consumption by TypeaheadSearch.
			 *
			 * @param pages
			 * @return
			 */
			function adaptApiResponse( pages ) {
				return pages.map( ( { id, key, title, description, thumbnail } ) => ( {
					label: title,
					value: id,
					description: description,
					url: `https://en.wikipedia.org/wiki/${encodeURIComponent( key )}`,
					thumbnail: thumbnail ? {
						url: thumbnail.url,
						width: thumbnail.width,
						height: thumbnail.height
					} : undefined
				} ) );
			}

			fetch(
				`https://en.wikipedia.org/w/rest.php/v1/search/title?q=${encodeURIComponent( value )}&limit=10&`
			).then( ( resp ) => resp.json() )
				.then( ( data ) => {
					if ( currentSearchTerm.value === value ) {
						searchResults.value = data.pages && data.pages.length > 0 ?
							adaptApiResponse( data.pages ) :
							[];

						searchFooterUrl.value = `https://en.wikipedia.org/w/index.php?title=Special%3ASearch&fulltext=1&search=${encodeURIComponent( value )}`;

					}
				} ).catch( () => {
					searchResults.value = [];
					searchFooterUrl.value = '';
				} );
		}

		return {
			searchResults,
			searchFooterUrl,
			onInput
		};
	}
} );
</script>

Pending state

Pending state indicators, including an inline progress bar and a message stating that results are pending, can be displayed to users with slower connections while search results are being fetched. To enable this, provide content in the search-results-pending slot.

The pending state indicators will display when a search takes longer than half a second, so you may need to throttle your connection to see them in the demo below.

NPMMediaWiki

vue

<template>
	<cdx-typeahead-search
		id="typeahead-search-pending-state"
		form-action="https://en.wikipedia.org/w/index.php"
		button-label="Search"
		search-results-label="Search results"
		:search-results="searchResults"
		:search-footer-url="searchFooterUrl"
		:show-thumbnail="true"
		:highlight-query="true"
		:auto-expand-width="true"
		placeholder="Search Wikipedia"
		@input="onInput"
	>
		<template #default>
			<input
				type="hidden"
				name="language"
				value="en"
			>
			<input
				type="hidden"
				name="title"
				value="Special:Search"
			>
		</template>
		<template #search-results-pending>
			Loading search results...
		</template>
		<template #search-footer-text="{ searchQuery }">
			Search Wikipedia for pages containing
			<strong class="cdx-typeahead-search__search-footer__query">
				{{ searchQuery }}
			</strong>
		</template>
	</cdx-typeahead-search>
</template>

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

export default defineComponent( {
	name: 'TypeaheadSearchPendingState',
	components: { CdxTypeaheadSearch },
	setup() {
		const searchResults = ref( [] );
		const searchFooterUrl = ref( '' );
		const currentSearchTerm = ref( '' );

		/**
		 * Format search results for consumption by TypeaheadSearch.
		 *
		 * @param pages
		 * @return
		 */
		function adaptApiResponse( pages ) {
			return pages.map( ( { id, key, title, description, thumbnail } ) => ( {
				label: title,
				value: id,
				description: description,
				url: `https://en.wikipedia.org/wiki/${encodeURIComponent( key )}`,
				thumbnail: thumbnail ? {
					url: thumbnail.url,
					width: thumbnail.width,
					height: thumbnail.height
				} : undefined
			} ) );
		}

		function onInput( value ) {
			// Internally track the current search term.
			currentSearchTerm.value = value;

			// Unset search results and the search footer URL if there is no value.
			if ( !value || value === '' ) {
				searchResults.value = [];
				searchFooterUrl.value = '';
				return;
			}

			fetch(
				`https://en.wikipedia.org/w/rest.php/v1/search/title?q=${encodeURIComponent( value )}&limit=10&`
			).then( ( resp ) => resp.json() )
				.then( ( data ) => {
					// Make sure this data is still relevant first.
					if ( currentSearchTerm.value === value ) {
						// If there are results, format them into an array of
						// SearchResults to be passed into TypeaheadSearch for
						// display as a menu of suggestions.
						searchResults.value = data.pages && data.pages.length > 0 ?
							adaptApiResponse( data.pages ) :
							[];

						// Set the search footer URL to a link to the search
						// page for the current search query.
						searchFooterUrl.value = `https://en.wikipedia.org/w/index.php?title=Special%3ASearch&fulltext=1&search=${encodeURIComponent( value )}`;

					}
				} ).catch( () => {
					// On error, reset search results and search footer URL.
					searchResults.value = [];
					searchFooterUrl.value = '';
				} );
		}

		return {
			searchResults,
			searchFooterUrl,
			onInput
		};
	}
} );
</script>

vue

<template>
	<cdx-typeahead-search
		id="typeahead-search-pending-state"
		form-action="https://en.wikipedia.org/w/index.php"
		button-label="Search"
		search-results-label="Search results"
		:search-results="searchResults"
		:search-footer-url="searchFooterUrl"
		:show-thumbnail="true"
		:highlight-query="true"
		:auto-expand-width="true"
		placeholder="Search Wikipedia"
		@input="onInput"
	>
		<template #default>
			<input
				type="hidden"
				name="language"
				value="en"
			>
			<input
				type="hidden"
				name="title"
				value="Special:Search"
			>
		</template>
		<template #search-results-pending>
			Loading search results...
		</template>
		<template #search-footer-text="{ searchQuery }">
			Search Wikipedia for pages containing
			<strong class="cdx-typeahead-search__search-footer__query">
				{{ searchQuery }}
			</strong>
		</template>
	</cdx-typeahead-search>
</template>

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

// @vue/component
module.exports = defineComponent( {
	name: 'TypeaheadSearchPendingState',
	components: { CdxTypeaheadSearch },
	setup() {
		const searchResults = ref( [] );
		const searchFooterUrl = ref( '' );
		const currentSearchTerm = ref( '' );

		/**
		 * Format search results for consumption by TypeaheadSearch.
		 *
		 * @param pages
		 * @return
		 */
		function adaptApiResponse( pages ) {
			return pages.map( ( { id, key, title, description, thumbnail } ) => ( {
				label: title,
				value: id,
				description: description,
				url: `https://en.wikipedia.org/wiki/${encodeURIComponent( key )}`,
				thumbnail: thumbnail ? {
					url: thumbnail.url,
					width: thumbnail.width,
					height: thumbnail.height
				} : undefined
			} ) );
		}

		function onInput( value ) {
			// Internally track the current search term.
			currentSearchTerm.value = value;

			// Unset search results and the search footer URL if there is no value.
			if ( !value || value === '' ) {
				searchResults.value = [];
				searchFooterUrl.value = '';
				return;
			}

			fetch(
				`https://en.wikipedia.org/w/rest.php/v1/search/title?q=${encodeURIComponent( value )}&limit=10&`
			).then( ( resp ) => resp.json() )
				.then( ( data ) => {
					// Make sure this data is still relevant first.
					if ( currentSearchTerm.value === value ) {
						// If there are results, format them into an array of
						// SearchResults to be passed into TypeaheadSearch for
						// display as a menu of suggestions.
						searchResults.value = data.pages && data.pages.length > 0 ?
							adaptApiResponse( data.pages ) :
							[];

						// Set the search footer URL to a link to the search
						// page for the current search query.
						searchFooterUrl.value = `https://en.wikipedia.org/w/index.php?title=Special%3ASearch&fulltext=1&search=${encodeURIComponent( value )}`;

					}
				} ).catch( () => {
					// On error, reset search results and search footer URL.
					searchResults.value = [];
					searchFooterUrl.value = '';
				} );
		}

		return {
			searchResults,
			searchFooterUrl,
			onInput
		};
	}
} );
</script>

No results message

A message prompt that no search results were found. To enable this, provide content in the search-no-results-text slot.

NPMMediaWiki

vue

<template>
	<cdx-typeahead-search
		id="typeahead-search-no-result"
		form-action="https://en.wikipedia.org/w/index.php"
		button-label="Search"
		search-results-label="Search results"
		:search-results="searchResults"
		:search-footer-url="searchFooterUrl"
		:show-thumbnail="true"
		:highlight-query="true"
		:auto-expand-width="true"
		placeholder="Search Wikipedia"
		@input="onInput"
	>
		<template #default>
			<input
				type="hidden"
				name="language"
				value="en"
			>
			<input
				type="hidden"
				name="title"
				value="Special:Search"
			>
		</template>
		<template #search-no-results-text>
			No results found
		</template>
		<template #search-footer-text="{ searchQuery }">
			Search Wikipedia for pages containing
			<strong class="cdx-typeahead-search__search-footer__query">
				{{ searchQuery }}
			</strong>
		</template>
	</cdx-typeahead-search>
</template>

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

export default defineComponent( {
	name: 'TypeaheadSearchNoResult',
	components: { CdxTypeaheadSearch },
	setup() {
		const searchResults = ref( [] );
		const searchFooterUrl = ref( '' );
		const currentSearchTerm = ref( '' );

		/**
		 * Format search results for consumption by TypeaheadSearch.
		 *
		 * @param pages
		 * @return
		 */
		function adaptApiResponse( pages ) {
			return pages.map( ( { id, key, title, description, thumbnail } ) => ( {
				label: title,
				value: id,
				description: description,
				url: `https://en.wikipedia.org/wiki/${encodeURIComponent( key )}`,
				thumbnail: thumbnail ? {
					url: thumbnail.url,
					width: thumbnail.width,
					height: thumbnail.height
				} : undefined
			} ) );
		}

		function onInput( value ) {
			// Internally track the current search term.
			currentSearchTerm.value = value;

			// Unset search results and the search footer URL if there is no value.
			if ( !value || value === '' ) {
				searchResults.value = [];
				searchFooterUrl.value = '';
				return;
			}

			fetch(
				`https://en.wikipedia.org/w/rest.php/v1/search/title?q=${encodeURIComponent( value )}&limit=10&`
			).then( ( resp ) => resp.json() )
				.then( ( data ) => {
					// Make sure this data is still relevant first.
					if ( currentSearchTerm.value === value ) {
						// If there are results, format them into an array of
						// SearchResults to be passed into TypeaheadSearch for
						// display as a menu of suggestions.
						searchResults.value = data.pages && data.pages.length > 0 ?
							adaptApiResponse( data.pages ) :
							[];

						// Set the search footer URL to a link to the search
						// page for the current search query.
						searchFooterUrl.value = `https://en.wikipedia.org/w/index.php?title=Special%3ASearch&fulltext=1&search=${encodeURIComponent( value )}`;

					}
				} ).catch( () => {
					// On error, reset search results and search footer URL.
					searchResults.value = [];
					searchFooterUrl.value = '';
				} );
		}

		return {
			searchResults,
			searchFooterUrl,
			onInput
		};
	}
} );
</script>

vue

<template>
	<cdx-typeahead-search
		id="typeahead-search-no-result"
		form-action="https://en.wikipedia.org/w/index.php"
		button-label="Search"
		search-results-label="Search results"
		:search-results="searchResults"
		:search-footer-url="searchFooterUrl"
		:show-thumbnail="true"
		:highlight-query="true"
		:auto-expand-width="true"
		placeholder="Search Wikipedia"
		@input="onInput"
	>
		<template #default>
			<input
				type="hidden"
				name="language"
				value="en"
			>
			<input
				type="hidden"
				name="title"
				value="Special:Search"
			>
		</template>
		<template #search-no-results-text>
			No results found
		</template>
		<template #search-footer-text="{ searchQuery }">
			Search Wikipedia for pages containing
			<strong class="cdx-typeahead-search__search-footer__query">
				{{ searchQuery }}
			</strong>
		</template>
	</cdx-typeahead-search>
</template>

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

// @vue/component
module.exports = defineComponent( {
	name: 'TypeaheadSearchNoResult',
	components: { CdxTypeaheadSearch },
	setup() {
		const searchResults = ref( [] );
		const searchFooterUrl = ref( '' );
		const currentSearchTerm = ref( '' );

		/**
		 * Format search results for consumption by TypeaheadSearch.
		 *
		 * @param pages
		 * @return
		 */
		function adaptApiResponse( pages ) {
			return pages.map( ( { id, key, title, description, thumbnail } ) => ( {
				label: title,
				value: id,
				description: description,
				url: `https://en.wikipedia.org/wiki/${encodeURIComponent( key )}`,
				thumbnail: thumbnail ? {
					url: thumbnail.url,
					width: thumbnail.width,
					height: thumbnail.height
				} : undefined
			} ) );
		}

		function onInput( value ) {
			// Internally track the current search term.
			currentSearchTerm.value = value;

			// Unset search results and the search footer URL if there is no value.
			if ( !value || value === '' ) {
				searchResults.value = [];
				searchFooterUrl.value = '';
				return;
			}

			fetch(
				`https://en.wikipedia.org/w/rest.php/v1/search/title?q=${encodeURIComponent( value )}&limit=10&`
			).then( ( resp ) => resp.json() )
				.then( ( data ) => {
					// Make sure this data is still relevant first.
					if ( currentSearchTerm.value === value ) {
						// If there are results, format them into an array of
						// SearchResults to be passed into TypeaheadSearch for
						// display as a menu of suggestions.
						searchResults.value = data.pages && data.pages.length > 0 ?
							adaptApiResponse( data.pages ) :
							[];

						// Set the search footer URL to a link to the search
						// page for the current search query.
						searchFooterUrl.value = `https://en.wikipedia.org/w/index.php?title=Special%3ASearch&fulltext=1&search=${encodeURIComponent( value )}`;

					}
				} ).catch( () => {
					// On error, reset search results and search footer URL.
					searchResults.value = [];
					searchFooterUrl.value = '';
				} );
		}

		return {
			searchResults,
			searchFooterUrl,
			onInput
		};
	}
} );
</script>

Vue usage

TypeaheadSearch contains a form with a text input, a submit button, and a slot for hidden inputs. The parent component must listen for changes in the search query (which are debounced by default), fetch or calculate search results, then provide them as an array of search results for display to the user in a dropdown menu.

At the end of the list of search results, a final option to go to the search page for the current search query is provided.

Events are emitted to the parent when a search result is selected and when the form is submitted, with data about the selected item (e.g. for analytics).

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
`id`^(required)	ID attribute for the form.	`string`
`formAction`^(required)	Action attribute for form.	`string`
`searchResultsLabel`^(required)	Label attribute for the list of search results.	`string`
`searchResults`^(required)	List of search results. See the SearchResult type.	`SearchResult[]`
`buttonLabel`	Label for the submit button. If no label is provided, the submit button will not be displayed.	`string`	`''`
`initialInputValue`	Initial value for the text input. Triggers an initial `input` event on mount.	`string`	`''`
`searchFooterUrl`	Link for the final menu item. This will typically be a link to the search page for the current search query.	`string`	`''`
`debounceInterval`	Time interval for debouncing input events, in ms.	`number`	`DebounceInterval`
`highlightQuery`	Whether the search query should be highlighted within a search result's title.	`boolean`	`false`
`showThumbnail`	Whether to show search results' thumbnails (or a placeholder icon).	`boolean`	`false`
`autoExpandWidth`	Contract the width of the input when unfocused and expand the width of the input when focused to accommodate the extra width of the thumbnails. This prop is ignored if showThumbnail is false.	`boolean`	`false`
`visibleItemLimit`	Limit the number of menu items to display before scrolling. Setting this prop to anything falsy will show all menu items. By default, all menu items are shown.	`number\|null`	`null`

Methods

Method name	Description	Signature
`focus`	Focus the component's input element.	Returns: `void`

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.
`input`	value `string` - The new input value	When the text input value changes. Debounced by default.
`search-result-click`	event `SearchResultClickEvent` - Data for the selected result	When a search result is selected.
`submit`	event `SearchResultClickEvent` - Data for the selected result	When the form is submitted.

Slots

Name	Description	Bindings
search-results-pending	A slot for a translated "Loading search results" message.
search-no-results-text	A slot for passing in a translated "no results" message.
search-footer-text	A slot for passing in translated search footer text.	search-query `string` - Input text entered by the user
default	A slot for passing hidden inputs, i.e. `<input type="hidden" name="language" value="en">`

CSS-only version

Markup structure

The CSS-only version of TypeaheadSearch is simply a SearchInput component styled to look like the Vue version of TypeaheadSearch. It will have no menu of results and is meant to be replaced by the Vue component once JavaScript has loaded. If you just need a SearchInput, check out the CSS-only version of the SearchInput component. Note that the search icon is automatically added for you.

With thumbnails

When your CSS-only TypeaheadSearch component will be swapped out for a Vue version that shows thumbnails (see the "With initial input value" demo above), apply the .cdx-typeahead-search--show-thumbnail class to the wrapper <div> to expand the start icon width.

With thumbnails and auto-expand width

When your CSS-only TypeaheadSearch component will be swapped out for a Vue version that shows thumbnails and expands when results are shown (see the "Search Wikipedia articles" demo above), apply the .cdx-typeahead-search--show-thumbnail and .cdx-typeahead-search--auto-expand-width classes to the wrapper <div> to reduce the starting size of the input.

TypeaheadSearch ​

Guidelines ​

Using TypeaheadSearch ​

Specifications ​

Types ​

Interaction states ​

Demos ​

Search Wikipedia articles ​

Search Wikidata items ​

With initial input value ​

Pending state ​

No results message ​

Vue usage ​

Props ​

Methods ​

Events ​

Slots ​

CSS-only version ​

Markup structure ​

With thumbnails ​

With thumbnails and auto-expand width ​

TypeaheadSearch

Guidelines

Using TypeaheadSearch

Specifications

Types

Interaction states

Demos

Search Wikipedia articles

Search Wikidata items

With initial input value

Pending state

No results message

Vue usage

Props

Methods

Events

Slots

CSS-only version

Markup structure

With thumbnails

With thumbnails and auto-expand width