DocSearch provides an easy way for Open Source documentations to have an instant search on their websites!
You probably have seen it in a lot of websites with the Cmd+K shortcut!
Websites like nuxtjs.org, vuejs.org uses it to provide an instant search to users without any backend!
As DocSearch is an additional feature for @nuxt-modules/algolia, it needs two additional dependencies:
yarn add @docsearch/js @docsearch/cssYou can easily configure DocSearch usage via the docSearch key in the module configuration.
By default, it is set to false, which disables it and does not ship anything to your Nuxt app bundle.
// nuxt.config.tsexport default defineNuxtConfig({ algolia: { apiKey: 'apiKey', applicationId: 'applicationId', // DocSearch key is used to configure DocSearch extension. docSearch: { indexName: 'indexName', } } })indexName
type: string| required
Your Algolia index name.
placeholder
type: string| `default: "Search docs" | optional
The placeholder of the input of the DocSearch pop-up modal.
searchParameters
type: SearchParameters| optional
The Algolia Search Parameters.
disableUserPersonalization
type: boolean|default: false| optional
Disable saving recent searches and favorites to the local storage.
initialQuery
type: string| optional
The search input initial query.
translations
type: Partial<DocSearchTranslations>|default: docSearchTranslations| optional
Allow translations of any raw text and aria-labels present in the DocSearch button or modal components.
const translations: DocSearchTranslations = { button: { buttonText: 'Search', buttonAriaLabel: 'Search', }, modal: { searchBox: { resetButtonTitle: 'Clear the query', resetButtonAriaLabel: 'Clear the query', cancelButtonText: 'Cancel', cancelButtonAriaLabel: 'Cancel', }, startScreen: { recentSearchesTitle: 'Recent', noRecentSearchesText: 'No recent searches', saveRecentSearchButtonTitle: 'Save this search', removeRecentSearchButtonTitle: 'Remove this search from history', favoriteSearchesTitle: 'Favorite', removeFavoriteSearchButtonTitle: 'Remove this search from favorites', }, errorScreen: { titleText: 'Unable to fetch results', helpText: 'You might want to check your network connection.', }, footer: { selectText: 'to select', selectKeyAriaLabel: 'Enter key', navigateText: 'to navigate', navigateUpKeyAriaLabel: 'Arrow up', navigateDownKeyAriaLabel: 'Arrow down', closeText: 'to close', closeKeyAriaLabel: 'Escape key', searchByText: 'Search by', }, noResultsScreen: { noResultsText: 'No results for', suggestedQueryText: 'Try searching for', reportMissingResultsText: 'Believe this query should return results?', reportMissingResultsLinkText: 'Let us know.', }, },};facetFilters
type: string| optional
The facetFilters to use in your search parameters. This is local shorthand and provided by @nuxtjs/algolia.
This will be overwritten if you add facetFilters into your searchOptions object.
langAttribute
type: string|default: 'language'| optional
The language to prefix all your facetFilters with. This will be overwritten if you add facetFilters into your searchOptions object. This is local shorthand and provided by @nuxtjs/algolia.
lang
type: string| optional
Default language to be used on the Algolia DocSearch client.
If defined, @nuxtjs/algolia will add an additional filter to the facetFilters array like this:
const facetFilters = [ `${options.langAttribute}:${options.lang}`, ...options.facetFilters]For example, with the following configuration:
// nuxt.config.tsexport default defineNuxtConfig({ algolia: { docSearch: { // ... other options lang: 'en', facetFilters: ['category:Book'] } } })The facetFilters sent by @nuxtjs/algolia will look like this:
['language:en', 'category:Book'] You can easily add the component anywhere in your app like this:
<template> <AlgoliaDocSearch /></template>The component will use the configuration values declared in nuxt.config.ts.
You can pass the configuration directly to the component as well if it's more convenient for you, like this:
<template> <AlgoliaDocSearch applicationId="appId" apiKey="key" indexName="indexName" placeholder="Search" :searchParameters="{}" :disableUserPersonalization="false" initialQuery="" :translations="{}" /></template>nuxt.config.ts and as a component prop, the latter takes precedence.These options are only available as component props.
transformItems
type: function|default: items => items| optional
Receives the items from the search response, and is called before displaying them. Should return a new array with the same shape as the original array. Useful for mapping over the items to transform, and remove or reorder them.
<template> <AlgoliaDocSearch :transform-items="(items) => { return items.map((item) => ({ ...item, content: item.content.toUpperCase(), })); }" /></template>hitComponent
type: ({ hit, children }) => JSX.Element|default: Hit| optional
The component to display each item.
See the default implementation.
transformSearchClient
type: function|default: searchClient => searchClient| optional
Useful for transforming the Algolia Search Client, for example to debounce search queries:
<template> <AlgoliaDocSearch :transform-search-client="transformSearchClient" /></template><script setup lang="ts">import type { SearchClient } from 'algoliasearch'import type { DocSearchProps } from 'docsearch'const transformSearchClient: DocSearchProps['transformSearchClient'] = (searchClient) => { return { ...searchClient, search: debounce(searchClient.search, 5000) } as SearchClient}function debounce (func: (...args: unknown[]) => unknown, wait = 100) { let lastTimeout = null return function (...args) { const that = this return new Promise((resolve, reject) => { if (lastTimeout) { clearTimeout(lastTimeout) } lastTimeout = setTimeout(() => { lastTimeout = null Promise.resolve(func.apply(that, args)).then(resolve).catch(reject) }, wait) }) }}</script>navigator
type: Navigator| optional
An implementation of Algolia Autocomplete’s Navigator API to redirect the user when opening a link.
Learn more on the Navigator API documentation.
getMissingResultsUrl
type: ({ query: string }) => string| optional
Function to return the URL of your documentation repository.
<template> <AlgoliaDocSearch :get-missing-results-url="getMissingResultsUrl" /></template><script setup lang="ts">import type { DocSearchProps } from 'docsearch'const getMissingResultsUrl: DocSearchProps['getMissingResultsUrl'] = ({ query }) => { return `https://github.com/algolia/docsearch/issues/new?title=${query}`;}</script>If you want to theme the component, you can use these files as a reference for available variables/classes:
The components gets shipped with @docsearch/css which is the default theme from Algolia.