@meilisearch/autocomplete-client
Advanced tools
The search client to use Meilisearch with autocomplete.js.
Meilisearch is an open-source search engine. Discover what Meilisearch is!
This library is the search client that you should use to make Meilisearch work with autocomplete. Autocomplete, an open-source project developed by Algolia, is a library that lets you quickly build an autocomplete experience.
Since autocomplete.js provides the possibility to use a custom data source, we are able to plug into it. Nonetheless, it has been created by Algolia and thus some of its components only works with Algolia.
For general information on how to use Meilisearch—such as our API reference, tutorials, guides, and in-depth articles—refer to our main documentation website.
For information on how to use the autocomplete library refer to its documentation. It provides all the necessary information to set up your autocomplete experience.
Say goodbye to server deployment and manual updates with Meilisearch Cloud. No credit card required.
Use npm or pnpm to install the autocomplete client for Meilisearch.
pnpm add @meilisearch/autocomplete-client
# or
npm install @meilisearch/autocomplete-client
@meilisearch/autocomplete-client is a client for autocomplete. It does not import the library.
To be able to use both, you need to install autocomplete as well.
The Meilisearch Autocomplete client provides 2 methods:
meilisearchAutocompleteClient({ host, url, options? }): The search client.
url: The URL to your Meilisearch instance.apiKey: A valid API key with enough rights to search. ⚠️ Avoid using the admin key or master keyoptions: Additional options. See this sectiongetMeilisearchResults(searchClient, queries): The data source handler.
searchClient: The client created with meilisearchAutocompleteClientqueries: An array of queries. See this documentation on what queries accepts.To make autocomplete work with Meilisearch, create the autocompleteSearchClient and provide it to the getMeilisearchResults method as the searchClient.
The following code provides a basic working code example.
import { autocomplete } from '@algolia/autocomplete-js'
import {
meilisearchAutocompleteClient,
getMeilisearchResults,
} from '@meilisearch/autocomplete-client'
import '@algolia/autocomplete-theme-classic'
const searchClient = meilisearchAutocompleteClient({
url: 'https://ms-adf78ae33284-106.lon.meilisearch.io', // Host
apiKey: 'a63da4928426f12639e19d62886f621130f3fa9ff3c7534c5d179f0f51c4f303' // API key
})
autocomplete({
container: '#autocomplete',
placeholder: 'Search for games',
getSources({ query }) {
return [
{
sourceId: 'steam-video-games',
getItems() {
return getMeilisearchResults({
searchClient,
queries: [
{
indexName: 'steam-video-games',
query,
},
],
})
},
templates: {
item({ item, components, html }) {
return html`<div>
<div>${item.name}</div>
</div>`
},
},
},
]
},
})
The options field in the meilisearchAutocompleteClient function provides the possibility to alter the default behavior of the search.
placeholderSearch: Enable or disable placeholder search (default: true).primaryKey: Specify the primary key of your documents (default undefined).keepZeroFacets: Show the facets value even when they have 0 matches (default false).requestConfig: Use custom request configurations.httpClient: Use a custom HTTP client.meiliSearchParams: Override search parameters sent to Meilisearch.const client = meilisearchAutocompleteClient({
url: 'http://localhost:7700',
apiKey: 'searchKey',
options: {
// other options
meiliSearchParams: {
},
},
})
Placeholders search means showing results even when the search query is empty. By default it is true.
When placeholder search is set to false, no results appears when the search box is empty.
{ placeholderSearch : true } // default true
Specify the field in your documents containing the unique identifier (undefined by default). By adding this option, we avoid errors that are thrown in some environments. For example, In React particularly, this option removes the Each child in a list should have a unique "key" prop error.
{ primaryKey : 'id' } // default: undefined
keepZeroFacets set to true keeps the facets even when they have 0 matching documents (default false).
If in your autocomplete implementation you are showing the facet values distribution, same values may completely disapear when they have no matching documents in the current filtering state.
By setting this option to true, the facet values do not disapear and instead are given the distribution 0.
With keepZeroFacets set to true:
genres:
With keepZeroFacets set to false, comedy disapears:
genres:
{ keepZeroFacets : true } // default: false
You can provide a custom request configuration. Available field can be found here.
For example, with custom headers:
{
requestConfig: {
headers: {
Authorization: AUTH_TOKEN
},
credentials: 'include'
}
}
You can use your own HTTP client, for example, with axios.
{
httpClient: async (url, opts) => {
const response = await $axios.request({
url,
data: opts?.body,
headers: opts?.headers,
method: (opts?.method?.toLocaleUpperCase() as Method) ?? 'GET'
})
return response.data
}
}
meiliSearchParams lets you override the parameters sent to Meilisearch.
The following options can be overridden:
attributesToCropattributesToHighlightattributesToRetrieveattributesToSearchOncropLengthcropMarkerdistincthighlightPreTag, highlightPostTaghybridmatchingStrategyshowMatchesPositionshowRankingScorerankingScoreThreshold[!NOTE] Search metadata is enabled by default on Meilisearch Cloud.
Search metadata is useful for interacting with the Meilisearch Analytics Events.
Each Autocomplete item (hit) includes an optional _meilisearch.metadata field when search metadata is enabled. You can use the getItemAnalyticsMetadata helper to retrieve the metadata and build event payloads for the /events endpoint:
import { autocomplete } from '@algolia/autocomplete-js'
import {
meilisearchAutocompleteClient,
getMeilisearchResults,
getItemAnalyticsMetadata,
} from '@meilisearch/autocomplete-client'
import '@algolia/autocomplete-theme-classic'
const searchClient = meilisearchAutocompleteClient({
url: 'https://ms-adf78ae33284-106.lon.meilisearch.io',
apiKey: 'a63da4928426f12639e19d62886f621130f3fa9ff3c7534c5d179f0f51c4f303'
})
autocomplete({
container: '#autocomplete',
placeholder: 'Search for movies',
getSources({ query }) {
return [
{
sourceId: 'movies',
getItems() {
return getMeilisearchResults({
searchClient,
queries: [{ indexName: 'movies', query }],
})
},
templates: {
item({ item, components, html }) {
return html`<div>${item.title}</div>`
},
},
onSelect({ item }) {
// Get metadata from the item
const metadata = getItemAnalyticsMetadata(item)
if (metadata) {
// Build and send click event to Meilisearch Cloud Analytics
fetch('https://ms-adf78ae33284-106.lon.meilisearch.io/events', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY',
},
body: JSON.stringify({
eventType: 'click',
eventName: 'Search Result Clicked',
indexUid: metadata.indexUid,
queryUid: metadata.queryUid,
objectId: item.objectID,
position: item.__position,
userId: 'user-123', // optional: required for conversion attribution
}),
})
}
},
},
]
},
})
For self-hosted Meilisearch instances, you need to enable search metadata by setting the Meili-Include-Metadata header:
const searchClient = meilisearchAutocompleteClient({
url: 'http://localhost:7700',
apiKey: 'your-api-key',
options: {
requestConfig: {
headers: {
'Meili-Include-Metadata': 'true'
}
}
}
})
Supported autocomplete versions:
This package only guarantees the compatibility with the version v1.x.x of Autocomplete. It may work with older or newer versions, but these are not tested nor officially supported at this time.
API compatibility with autocomplete
Some autocomplete parameters are not working using the meilisearch autocomplete client.
Supported Meilisearch versions:
This package guarantees compatibility with version v1.x of Meilisearch, but some features may not be present. Please check the issues for more info.
Node / NPM versions:
Any new contribution is more than welcome in this project!
If you want to know more about the development workflow or want to contribute, please visit our contributing guidelines for detailed instructions!
Meilisearch provides and maintains many SDKs and Integration tools like this one. We want to provide everyone with an amazing search experience for any kind of project. If you want to contribute, make suggestions, or just know what's going on right now, visit us in the integration-guides repository.
FAQs
The search client to use Meilisearch with autocomplete.js.
The npm package @meilisearch/autocomplete-client receives a total of 1,447 weekly downloads. As such, @meilisearch/autocomplete-client popularity was classified as popular.
We found that @meilisearch/autocomplete-client demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A malicious NuGet package impersonating Sicoob exfiltrated client IDs, PFX passwords, and banking certificates through Sentry telemetry.
Security News
Feross Aboukhadijeh joins TBPN to discuss Socket's $60M Series C, 500%+ ARR growth, AI's impact on open source, and the rise in supply chain attacks.
Security News
OSV withdrew 157 OSV malware reports after automated false positives incorrectly flagged trusted npm and PyPI packages, sending bad records into tools that rely on OSV data.