Skip to main content

InstantSearch Adapter

This guide shows you how to use the @elasticpath/catalog-search-instantsearch-adapter package to build search experiences in your storefront using the popular InstantSearch.js library.

The adapter translates InstantSearch.js requests into Catalog Search API requests and transforms the responses back into InstantSearch format, giving you access to a rich ecosystem of pre-built search widgets.

tip

Before using the adapter, ensure you have Catalog Search enabled for your store. See Catalog Search in Commerce Manager to get started.

Features​

  • Seamless integration with InstantSearch.js widgets
  • Full-text search with highlighting
  • Faceted search and filtering
  • Pagination and result sorting
  • Support for both vanilla JavaScript and React InstantSearch

Installation​

Install the adapter along with the Elastic Path SDK and InstantSearch.js:

npm install @elasticpath/catalog-search-instantsearch-adapter @epcc-sdk/sdks-shopper instantsearch.js

For React applications:

npm install @elasticpath/catalog-search-instantsearch-adapter @epcc-sdk/sdks-shopper react-instantsearch instantsearch.js

Basic usage​

Configure the client​

First, configure the Elastic Path shopper client with your credentials:

import { configureClient, client } from '@epcc-sdk/sdks-shopper';

configureClient(
  {
    baseUrl: 'https://euwest.api.elasticpath.com',
  },
  {
    clientId: 'YOUR_CLIENT_ID',
    storage: 'localStorage', // Optional: persist tokens
  }
);

Create the adapter​

Create an instance of the adapter with your configured client:

import CatalogSearchInstantSearchAdapter from '@elasticpath/catalog-search-instantsearch-adapter';

const catalogSearchAdapter = new CatalogSearchInstantSearchAdapter({
  client: client,
});

Initialize InstantSearch​

Use the adapter's searchClient property when initializing InstantSearch:

import instantsearch from 'instantsearch.js';

const search = instantsearch({
  indexName: 'search',
  searchClient: catalogSearchAdapter.searchClient,
});

// Add widgets
search.addWidgets([
  instantsearch.widgets.searchBox({
    container: '#searchbox',
  }),
  instantsearch.widgets.hits({
    container: '#hits',
  }),
  instantsearch.widgets.refinementList({
    container: '#brand-list',
    attribute: 'extensions.products(product_brands).name',
  }),
]);

search.start();

React integration​

For React applications, use the react-instantsearch package:

import React from 'react';
import {
  InstantSearch,
  SearchBox,
  Hits,
  RefinementList,
  Pagination,
} from 'react-instantsearch';
import CatalogSearchInstantSearchAdapter from '@elasticpath/catalog-search-instantsearch-adapter';
import { configureClient, client } from '@epcc-sdk/sdks-shopper';

// Configure authentication (typically done once in your app initialization)
configureClient(
  {
    baseUrl: 'https://euwest.api.elasticpath.com',
  },
  {
    clientId: 'YOUR_CLIENT_ID',
    storage: 'localStorage',
  }
);

// Create the adapter
const catalogSearchAdapter = new CatalogSearchInstantSearchAdapter({
  client: client,
});

function Search() {
  return (
    <InstantSearch 
      indexName="search" 
      searchClient={catalogSearchAdapter.searchClient}
    >
      <SearchBox />
      <div className="search-panel">
        <div className="search-panel__filters">
          <RefinementList attribute="extensions.products(product_brands).name" />
        </div>
        <div className="search-panel__results">
          <Hits />
          <Pagination />
        </div>
      </div>
    </InstantSearch>
  );
}

Index name configuration​

The indexName parameter determines which Elastic Path search endpoint to use:

Index NameUsage
searchRegular product search (required)
autocompleteAutocomplete and suggestions

These values map directly to the type parameter in Elastic Path's Catalog Search API.

Supported widgets​

The adapter supports most InstantSearch widgets out of the box.

Search widgets​

  • searchBox - Basic search input
  • autocomplete - Search with suggestions (use with indexName: 'autocomplete')
  • voiceSearch - Voice input support

Results widgets​

  • hits - Display search results
  • infiniteHits - Infinite scrolling results
  • highlight - Highlight matching terms
  • snippet - Show text snippets

Filtering widgets​

  • refinementList - Filter by facet values
  • hierarchicalMenu - Category navigation
  • rangeSlider / rangeInput - Numeric range filters
  • toggleRefinement - Boolean filters
  • clearRefinements - Clear all filters
  • currentRefinements - Show active filters

Pagination widgets​

  • pagination - Page navigation
  • hitsPerPage - Results per page selector

Metadata widgets​

  • stats - Search statistics
  • breadcrumb - Navigation breadcrumb

Widgets with limitations​

  • geoSearch - Not supported (Catalog Search does not support geo-search)
  • queryRuleCustomData - Limited support
  • sortBy - Use configure widget with additionalSearchParameters.sort_by

Widget examples​

Hierarchical categories​

instantsearch.widgets.hierarchicalMenu({
  container: '#categories',
  attributes: [
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
  ],
});

Price range filter​

instantsearch.widgets.rangeSlider({
  container: '#price-range',
  attribute: 'price.float_price',
});

Searchable refinement list​

instantsearch.widgets.refinementList({
  container: '#brands',
  attribute: 'extensions.products(product_brands).name',
  limit: 10,
  showMore: true,
  showMoreLimit: 50,
  searchable: true,
  searchablePlaceholder: 'Search brands',
});

The adapter supports union search to query multiple collections simultaneously:

const adapter = new CatalogSearchInstantSearchAdapter({
  client: client,
  union: true,
});

Migrating from Algolia​

If you're migrating from Algolia to Elastic Path Catalog Search, most of your InstantSearch implementation will work without changes:

  1. Replace the Algolia search client with this adapter
  2. Update attribute names to match your Elastic Path catalog structure
  3. Configure authentication using the Elastic Path SDK instead of Algolia API keys
tip

See the complete InstantSearch example on GitHub for a full implementation.

Ask External AI