Typesense InstantSearch Adapter

To use the adapter, instantiate TypesenseInstantSearchAdapter with a configuration object. The configuration consists of two main parts:

1. server: Defines the connection to your Typesense cluster.
   • apiKey: A search-only API key.
   • nodes: An array of node objects containing host, port, protocol, and an optional path (e.g., '/typesense').
   • cacheSearchResultsForSeconds: Duration to cache results (defaults to 120 seconds; set to 0 to disable).
2. additionalSearchParameters: Parameters passed directly to the Typesense search API. query_by is required.

After instantiation, use the searchClient property to connect to your Instantsearch instance.

To control the display order of facets in the dynamicWidgets widget, use the renderingContent configuration with facetOrdering.

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [{ host: "localhost", port: "8108", path: "/", protocol: "http" }],
  },
  renderingContent: {
    facetOrdering: {
      facets: {
        order: ["size", "brand"],
      },
    },
  },
  additionalSearchParameters,
});

To use the hierarchicalMenu widget, your Typesense collection schema must include independent fields following a specific naming convention for each level of the hierarchy:

• field.lvl0
• field.lvl1
• field.lvl2

For a hierarchy of field.lvl0 > field.lvl1 > field.lvl2. Each field can hold an array of values to support multiple hierarchies.

Typesense allows any field name for geo-location. If you are not using the default _geoloc, you must specify the field name in the adapter configuration using geoLocationField.

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "xyz",
    nodes: [{ host: "localhost", port: "8108", path: "/", protocol: "http" }],
  },
  geoLocationField: "lat_lng_field",
  additionalSearchParameters,
});

Install the adapter and its required peer dependency @babel/runtime using npm or yarn.

Note: This is an adapter only. You must also manually install the specific Instantsearch library you intend to use (e.g., instantsearch.js, react-instantsearch, vue-instantsearch, or angular-instantsearch).

$ npm install --save typesense-instantsearch-adapter @babel/runtime

# or

$ yarn add typesense-instantsearch-adapter @babel/runtime

Use the following commands for local development, running the Typesense server, indexing test data, and running tests.

$ npm install
$ npm run typesenseServer
$ FORCE_REINDEX=true npm run indexTestData

$ npm link typesense-instantsearch-adapter
$ npm run testground

$ npm test

For multi-index search, use the index widget. To provide different search parameters for different collections, use the collectionSpecificSearchParameters option in the adapter configuration. These parameters are merged with additionalSearchParameters, effectively overriding them on a per-collection basis.

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: {
    apiKey: "abcd",
    nodes: [{ host: "localhost", path: "/", port: "8108", protocol: "http" }],
  },
  // Common to all collections
  additionalSearchParameters: {
    numTypos: 3,
  },
  // Overrides per collection
  collectionSpecificSearchParameters: {
    products: {
      query_by: "name,description,categories",
    },
    brands: {
      query_by: "name",
    },
  },
});
const searchClient = typesenseInstantsearchAdapter.searchClient;

When using the sortBy widget, the value attribute for each item must follow the pattern: <index_name>[/sort/<sort_by>]. The adapter extracts the <sort_by> portion to use as the Typesense sort_by search parameter.

Example pattern: products/sort/price:asc uses price:asc as the sort parameter.

search.addWidgets([
  sortBy({
    container: "#sort-by",
    items: [
      { label: "Default", value: "products" },
      { label: "Price (asc)", value: "products/sort/price:asc" },
      { label: "Price (desc)", value: "products/sort/price:desc" },
    ],
  }),
]);

By default, excluded values in refinementList are encoded as list filters (field:![a,b]). If you want to change how negative refinements are encoded, set flipNegativeRefinementOperator: true.

With this enabled:

• operator: "and" with negative values becomes field:![a,b].
• operator: "or" with negative values becomes (field:!a || field:!b).
• Positive OR behavior remains field:[a,b].

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: { /* ... */ },
  flipNegativeRefinementOperator: true,
  additionalSearchParameters,
});

You can include the adapter directly in your HTML using a script tag from JSDelivr. It is recommended to pin the version to avoid unexpected breaking changes from minor updates.

<script src="https://cdn.jsdelivr.net/npm/typesense-instantsearch-adapter@2/dist/typesense-instantsearch-adapter.min.js"></script>

To prevent the adapter from applying curation rules or overrides when a specific sort order is selected, use sortByOptions. The key in this object should be the Typesense sort_by string (e.g., price:asc). You can also use collectionSpecificSortByOptions for per-collection overrides.

const typesenseInstantsearchAdapter = new TypesenseInstantSearchAdapter({
  server: { /* ... */ },
  sortByOptions: {
    "field1:desc,field2:desc": { enable_overrides: false },
  },
  collectionSpecificSortByOptions: {
    collection2: {
      "field1:desc,field2:desc": { enable_overrides: false },
    },
  },
  additionalSearchParameters,
});