getAlgoliaFacets

Retrieve Algolia facet hits from one or several indices with autocomplete-preset-algolia.

Autocomplete is also available as an experimental widget in InstantSearch, making it easier to integrate into your search experience. For more information, see the API reference for InstantSearch.js or React InstantSearch.

The getAlgoliaFacets function lets you query facet hits from one or several Algolia indices.

Using getAlgoliaFacets lets Autocomplete batch all queries using the same search client into a single network call, and thus minimize search unit consumption. It also works out of the box with the components exposed in templates.

If you’re using autocomplete-js, you don’t need to import the preset separately. The package includes all Algolia utilities, with the appropriate user agents and virtual DOM support.

Installation

First, you need to install the preset.

npm

npm install @algolia/autocomplete-preset-algolia

yarn add @algolia/autocomplete-preset-algolia

Then import it in your project:

JavaScript

import { getAlgoliaFacets } from "@algolia/autocomplete-preset-algolia";

If you don’t use a package manager, you can use the HTML script element:

HTML

<script
  src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-preset-algolia@1.19.9/dist/umd/index.production.js"
  integrity="sha256-mbQPS+x0+jNL5Xw3QUxxFofMTi1IncKd/7o4dqP9PDY="
  crossorigin="anonymous"
></script>
<script>
  const { getFacetResults } = window["@algolia/autocomplete-preset-algolia"];
</script>

Example

JavaScript

import { liteClient as algoliasearch } from "algoliasearch/lite";
import { createAutocomplete } from "@algolia/autocomplete-core";
import { getAlgoliaResults } from "@algolia/autocomplete-preset-algolia";

const searchClient = algoliasearch(
  "latency",
  "6be0576ff61c053d5f9a3225e2a90f76",
);

const autocomplete = createAutocomplete({
  // ...
  getSources() {
    return [
      {
        sourceId: "categories",
        getItems({ query }) {
          return getAlgoliaFacets({
            searchClient,
            queries: [
              {
                indexName: "instant_search",
                facet: "categories",
                params: {
                  facetQuery: query,
                  maxFacetHits: 10,
                },
              },
            ],
          });
        },
        // ...
      },
    ];
  },
});

Parameters

searchClient · SearchClient · required

The initialized Algolia search client.

queries · FacetQuery[] · required

The queries to search for.

Show FacetQuery properties

FacetQuery.indexName · string · required

The name.

FacetQuery.facet · string · required

The name of the facet attribute for which to search facet values.

The attribute must be declared in the attributesForFaceting index setting with the searchable() modifier.

FacetQuery.params · SearchForFacetValuesQueryParams

Algolia search for facet values parameters.

These are the default parameters. You can leave them as they are and specify other parameters, or override them.

JSON

{
  "highlightPreTag": "__aa-highlight__",
  "highlightPostTag": "__/aa-highlight__"
}

If you override highlightPreTag and highlightPostTag, you won’t be able to use the built-in highlighting components such as Highlight.

transformResponse · function

Type definition

(response: {
  results: Array<SearchResponse<THit> | SearchForFacetValuesResponse>,
  hits: MaybeArray<Hit<THit>[]>,
  facetHits: MaybeArray<FacetHit[]>,
}) => MaybeArray<Hit<THit>[] | FacetHit[]

The function to transform the Algolia response before passing it to the Autocomplete state. You have access to the full Algolia results, as well as the pre-computed hits and facet hits. This is useful to manipulate the hits, or store data from the results in the context.

This is the default implementation:

JavaScript

getAlgoliaFacets({
  // ...
  transformResponse({ facetHits }) {
    return facetHits;
  },
});

Returns

The function returns:

TypeScript

{
  searchClient: SearchClient;
  queries: MultipleQueriesQuery[];
  transformResponse: TransformResponse<THit>;
  execute: Execute<THit>;
}