@meilisearch/autocomplete-client

Autocomplete Meilisearch Client

Meilisearch | Meilisearch Cloud | Documentation | Discord | Roadmap | Website | FAQ

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.

Table of Contents

• 📖 Documentation
• ⚡ Supercharge your Meilisearch experience
• 🔧 Installation
• 🎬 Usage
• 🎬 Getting started
• 💅 Customization
• 🤖 Compatibility with Meilisearch and Autocomplete
• ⚙️ Development Workflow and Contributing

📖 Documentation

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.

⚡ Supercharge your Meilisearch experience

Say goodbye to server deployment and manual updates with Meilisearch Cloud. No credit card required.

🔧 Installation

Use npm or yarn to install the autocomplete client for Meilisearch.

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

🎬 Usage

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 key
  • options: Additional options. See this section
• getMeilisearchResults(searchClient, queries): The data source handler.
  • searchClient: The client created with meilisearchAutocompleteClient
  • queries: An array of queries. See this documentation on what queries accepts.

🎬 Getting started

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>`
          },
        },
      },
    ]
  },
})

💅 Customization

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).
• matchingStrategy: Determine the search strategy on words matching (default last).
• requestConfig: Use custom request configurations.
• 'httpClient': Use a custom HTTP client.

const client = meilisearchAutocompleteClient({
  url: 'http://localhost:7700',
  apiKey: 'searchKey',
  options: {
    placeholderSearch: false,
  },
})

Placeholder Search

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

Primary key

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

Keep zero facets

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:

• [x] horror (2000)
• [x] thriller (214)
• [ ] comedy (0)

With keepZeroFacets set to false, comedy disapears:

genres:

• [x] horror (2000)
• [x] thriller (214)

{ keepZeroFacets : true } // default: false

Matching strategy

matchingStrategy gives you the possibility to choose how Meilisearch should handle the presence of multiple query words, see documentation.

For example, if your query is hello world by default Meilisearch returns documents containing either both hello and world or documents that only contain hello. This is the last strategy, where words are stripped from the right. The other strategy is all, where both hello and world must be present in a document for it to be returned.

{ matchingStrategy: 'all' }  // default last

Request Config

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

Custom HTTP client

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

🤖 Compatibility with Meilisearch and Autocomplete

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.

• The autocomplete insights parameter
• The autocomplete-plugin-algolia-insights plugin

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:

• NodeJS >= 18

⚙️ Development Workflow and Contributing

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.