Basic Usage - InstantSearch

InstantSearch.js provides a comprehensive set of widgets to build search interfaces. All widgets follow a consistent API pattern. Every widget is a function that accepts an options object:

widgetName({
  container: '#selector',
  // widget-specific options
})

Widgets must be added before calling search.start():

import instantsearch from 'instantsearch.js';
import { searchBox, hits } from 'instantsearch.js/es/widgets';

const search = instantsearch({ /* options */ });

search.addWidgets([
  searchBox({ container: '#searchbox' }),
  hits({ container: '#hits' }),
]);

search.start();

Search Widgets

A search input with submit and reset buttons:

import { searchBox } from 'instantsearch.js/es/widgets';

searchBox({
  container: '#searchbox',
  placeholder: 'Search for products...',
  autofocus: true,
  searchAsYouType: true,
  showReset: true,
  showSubmit: true,
  showLoadingIndicator: true,
  queryHook: (query, search) => {
    // Modify query before searching (e.g., debouncing)
    search(query);
  },
  templates: {
    submit: ({ html }) => html`<span>🔍</span>`,
    reset: ({ html }) => html`<span>✕</span>`,
    loadingIndicator: ({ html }) => html`<span>⏳</span>`,
  },
  cssClasses: {
    root: 'my-SearchBox',
    form: 'my-SearchBox-form',
    input: 'my-SearchBox-input',
  },
})

Key Options:

searchAsYouType (default: true) - Search as user types vs. on submit only
queryHook - Transform query before search (useful for debouncing)
autofocus - Focus input on page load

hits

Display search results:

import { hits } from 'instantsearch.js/es/widgets';

hits({
  container: '#hits',
  templates: {
    item: (hit, { html, components, sendEvent }) => html`
      <article>
        <img src="${hit.image}" alt="${hit.name}" />
        <h3>${components.Highlight({ hit, attribute: 'name' })}</h3>
        <p>${components.Snippet({ hit, attribute: 'description' })}</p>
        <span class="price">$${hit.price}</span>
        <button
          onClick="${() => sendEvent('click', hit, 'Product Clicked')}"
        >
          View Details
        </button>
      </article>
    `,
    empty: ({ html }) => html`
      <div class="no-results">
        <p>No results found</p>
      </div>
    `,
  },
  transformItems: (items) =>
    items.map((item) => ({
      ...item,
      price: (item.price / 100).toFixed(2), // Convert cents to dollars
    })),
  cssClasses: {
    root: 'my-Hits',
    list: 'my-Hits-list',
    item: 'my-Hits-item',
    emptyRoot: 'my-Hits--empty',
  },
})

Template Parameters:

html - Tagged template function for rendering
components - Highlight, Snippet, and other helper components
sendEvent - Function to track insights events

infiniteHits

Load more results with infinite scrolling:

import { infiniteHits } from 'instantsearch.js/es/widgets';

infiniteHits({
  container: '#infinite-hits',
  showPrevious: true,
  templates: {
    item: (hit, { html, components }) => html`
      <article>
        <h3>${components.Highlight({ hit, attribute: 'name' })}</h3>
      </article>
    `,
    showPreviousText: ({ html }) => html`<span>← Show previous</span>`,
    showMoreText: ({ html }) => html`<span>Show more →</span>`,
  },
  transformItems: (items) => items,
})

configure

Set search parameters without UI:

import { configure } from 'instantsearch.js/es/widgets';

configure({
  hitsPerPage: 20,
  attributesToSnippet: ['description:50'],
  snippetEllipsisText: '...',
  removeWordsIfNoResults: 'allOptional',
  distinct: 1,
  enablePersonalization: true,
  clickAnalytics: true,
  analytics: true,
  analyticsTags: ['desktop', 'search-page'],
})

Accepts any search parameter from the Algolia API.

Filtering Widgets

refinementList

Faceted search filters with checkboxes:

import { refinementList } from 'instantsearch.js/es/widgets';

refinementList({
  container: '#brand',
  attribute: 'brand',
  searchable: true,
  searchablePlaceholder: 'Search brands...',
  searchableIsAlwaysActive: true,
  showMore: true,
  showMoreLimit: 20,
  limit: 10,
  operator: 'or', // or 'and'
  sortBy: ['name:asc'], // or ['count:desc', 'name:asc']
  templates: {
    searchableNoResults: ({ html }) => html`<p>No brands found</p>`,
    showMoreText: ({ isShowingMore, html }) => html`
      <span>${isShowingMore ? 'Show less' : 'Show more'}</span>
    `,
    item: ({ label, count, isRefined, html }) => html`
      <label>
        <input type="checkbox" checked="${isRefined}" />
        <span>${label} (${count})</span>
      </label>
    `,
  },
  transformItems: (items) =>
    items.map((item) => ({
      ...item,
      label: item.label.toUpperCase(),
    })),
  cssClasses: {
    searchableInput: 'my-RefinementList-searchBox',
    showMore: 'my-RefinementList-showMore',
  },
})

Key Options:

attribute - Index attribute to filter on
operator - "or" (default) or "and" for combining values
searchable - Add search within facets
showMore - Enable “Show more” button

hierarchicalMenu

Multi-level categorization:

import { hierarchicalMenu } from 'instantsearch.js/es/widgets';

hierarchicalMenu({
  container: '#categories',
  attributes: [
    'hierarchicalCategories.lvl0',
    'hierarchicalCategories.lvl1',
    'hierarchicalCategories.lvl2',
  ],
  separator: ' > ',
  rootPath: null,
  showParentLevel: true,
  limit: 10,
  showMore: true,
  showMoreLimit: 20,
  sortBy: ['name:asc'],
  templates: {
    item: ({ label, count, html }) => html`
      <span>${label} <small>(${count})</small></span>
    `,
  },
})

Single-select filter:

import { menu } from 'instantsearch.js/es/widgets';

menu({
  container: '#category',
  attribute: 'category',
  limit: 10,
  showMore: true,
  showMoreLimit: 20,
  sortBy: ['name:asc'],
  templates: {
    item: ({ label, count, isRefined, html }) => html`
      <span class="${isRefined ? 'selected' : ''}">
        ${label} (${count})
      </span>
    `,
  },
})

rangeInput

Numeric range filter with min/max inputs:

import { rangeInput } from 'instantsearch.js/es/widgets';

rangeInput({
  container: '#price',
  attribute: 'price',
  min: 0,
  max: 1000,
  precision: 2,
  templates: {
    separatorText: ({ html }) => html`<span>to</span>`,
    submitText: ({ html }) => html`<span>Apply</span>`,
  },
})

rangeSlider

Numeric range filter with slider:

import { rangeSlider } from 'instantsearch.js/es/widgets';

rangeSlider({
  container: '#price-slider',
  attribute: 'price',
  min: 0,
  max: 1000,
  step: 10,
  pips: true,
  precision: 2,
  tooltips: true,
})

The rangeSlider widget requires the nouislider library:

npm install nouislider

toggleRefinement

Boolean on/off filter:

import { toggleRefinement } from 'instantsearch.js/es/widgets';

toggleRefinement({
  container: '#free-shipping',
  attribute: 'free_shipping',
  on: true,
  off: false,
  templates: {
    labelText: ({ isRefined, html }) => html`
      <span>Free shipping ${isRefined ? '✓' : ''}</span>
    `,
  },
})

ratingMenu

Star rating filter:

import { ratingMenu } from 'instantsearch.js/es/widgets';

ratingMenu({
  container: '#rating',
  attribute: 'rating',
  max: 5,
  templates: {
    item: ({ stars, html }) => html`<span>${stars}</span>`,
  },
})

numericMenu

Predefined numeric ranges:

import { numericMenu } from 'instantsearch.js/es/widgets';

numericMenu({
  container: '#price-ranges',
  attribute: 'price',
  items: [
    { label: 'All' },
    { label: 'Under $25', end: 25 },
    { label: '$25 - $100', start: 25, end: 100 },
    { label: '$100 - $500', start: 100, end: 500 },
    { label: '$500 & above', start: 500 },
  ],
})

currentRefinements

Display active filters:

import { currentRefinements } from 'instantsearch.js/es/widgets';

currentRefinements({
  container: '#current-refinements',
  excludedAttributes: ['query'],
  includedAttributes: [], // Include only these attributes
  transformItems: (items) =>
    items.filter((item) => item.attribute !== 'internal_field'),
  cssClasses: {
    root: 'my-CurrentRefinements',
    list: 'my-CurrentRefinements-list',
    item: 'my-CurrentRefinements-item',
  },
})

clearRefinements

Clear all or specific filters:

import { clearRefinements } from 'instantsearch.js/es/widgets';

clearRefinements({
  container: '#clear-refinements',
  excludedAttributes: ['category'], // Don't clear these
  includedAttributes: [], // Only clear these
  templates: {
    resetLabel: ({ hasRefinements, html }) => html`
      <span>Clear ${hasRefinements ? 'all' : 'filters'}</span>
    `,
  },
})

pagination

Navigate between result pages:

import { pagination } from 'instantsearch.js/es/widgets';

pagination({
  container: '#pagination',
  totalPages: 20,
  padding: 3,
  showFirst: true,
  showPrevious: true,
  showNext: true,
  showLast: true,
  scrollTo: '#searchbox', // Scroll to element on page change
  templates: {
    first: ({ html }) => html`<span>‹‹</span>`,
    previous: ({ html }) => html`<span>‹</span>`,
    next: ({ html }) => html`<span>›</span>`,
    last: ({ html }) => html`<span>››</span>`,
    page: ({ page, html }) => html`<span>${page}</span>`,
  },
})

Show hierarchical navigation path:

import { breadcrumb } from 'instantsearch.js/es/widgets';

breadcrumb({
  container: '#breadcrumb',
  attributes: [
    'hierarchicalCategories.lvl0',
    'hierarchicalCategories.lvl1',
    'hierarchicalCategories.lvl2',
  ],
  separator: ' / ',
  rootPath: null,
  transformItems: (items) => items,
  templates: {
    home: ({ html }) => html`<span>Home</span>`,
    separator: ({ html }) => html`<span>/</span>`,
  },
})

Utility Widgets

stats

Display search statistics:

import { stats } from 'instantsearch.js/es/widgets';

stats({
  container: '#stats',
  templates: {
    text: ({ nbHits, processingTimeMS, query, html }) => html`
      <span>
        ${nbHits.toLocaleString()} results found in ${processingTimeMS}ms
        ${query ? `for "<strong>${query}</strong>"` : ''}
      </span>
    `,
  },
})

sortBy

Switch between index replicas:

import { sortBy } from 'instantsearch.js/es/widgets';

sortBy({
  container: '#sort-by',
  items: [
    { label: 'Relevance', value: 'products' },
    { label: 'Price (asc)', value: 'products_price_asc' },
    { label: 'Price (desc)', value: 'products_price_desc' },
    { label: 'Most popular', value: 'products_popularity_desc' },
  ],
})

hitsPerPage

Select results per page:

import { hitsPerPage } from 'instantsearch.js/es/widgets';

hitsPerPage({
  container: '#hits-per-page',
  items: [
    { label: '12 hits per page', value: 12, default: true },
    { label: '24 hits per page', value: 24 },
    { label: '48 hits per page', value: 48 },
  ],
})

poweredBy

Show “Search by Algolia” logo:

import { poweredBy } from 'instantsearch.js/es/widgets';

poweredBy({
  container: '#powered-by',
  theme: 'light', // or 'dark'
})

Advanced Widgets

panel

Wrap any widget with a header/footer:

import { panel, refinementList } from 'instantsearch.js/es/widgets';

panel({
  templates: {
    header: ({ html }) => html`<h3>Brands</h3>`,
    footer: ({ html }) => html`<p>Select brands to filter</p>`,
  },
  hidden: ({ results }) => results.nbHits === 0,
  collapsed: ({ state }) => !state.query,
  cssClasses: {
    root: 'my-Panel',
    header: 'my-Panel-header',
    body: 'my-Panel-body',
    footer: 'my-Panel-footer',
  },
})(refinementList)({
  container: '#brand-list',
  attribute: 'brand',
})

index

Query multiple indices:

import { index, hits, configure } from 'instantsearch.js/es/widgets';

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

search.addWidgets([
  searchBox({ container: '#searchbox' }),
  
  // Main index
  hits({ container: '#products' }),
  
  // Secondary index
  index({ indexName: 'categories' })
    .addWidgets([
      configure({ hitsPerPage: 3 }),
      hits({ container: '#categories' }),
    ]),
]);

search.start();

dynamicWidgets

Automatically render facets based on search results:

import { dynamicWidgets, refinementList, menu } from 'instantsearch.js/es/widgets';

dynamicWidgets({
  container: '#dynamic-widgets',
  widgets: [
    (container) => refinementList({ container, attribute: 'brand' }),
    (container) => menu({ container, attribute: 'category' }),
    (container) => refinementList({ container, attribute: 'color' }),
  ],
  fallbackWidget: ({ container, attribute }) =>
    refinementList({ container, attribute }),
})

AI-Powered Widgets

chat

Conversational search interface:

import { chat } from 'instantsearch.js/es/widgets';
import { carousel } from 'instantsearch.js/es/templates';

chat({
  container: '#chat',
  agentId: 'your-agent-id',
  templates: {
    item: (item, { html }) => html`
      <article>
        <img src="${item.image}" />
        <h3>${item.name}</h3>
      </article>
    `,
    layout: carousel(),
  },
})

filterSuggestions

AI-powered filter recommendations:

import { filterSuggestions } from 'instantsearch.js/es/widgets';

filterSuggestions({
  container: '#filter-suggestions',
  agentId: 'your-agent-id',
  attributes: ['brand', 'categories', 'color'],
  templates: {
    header: ({ html }) => html`<h3>Suggested Filters</h3>`,
  },
})

Recommendation Widgets

trendingItems

Show trending products:

import { trendingItems } from 'instantsearch.js/es/widgets';
import { carousel } from 'instantsearch.js/es/templates';

trendingItems({
  container: '#trending',
  limit: 6,
  templates: {
    item: (item, { html }) => html`
      <article>
        <img src="${item.image}" />
        <h3>${item.name}</h3>
        <span>$${item.price}</span>
      </article>
    `,
    layout: carousel(),
  },
})

relatedProducts

Show related products based on objectID:

import { relatedProducts } from 'instantsearch.js/es/widgets';

relatedProducts({
  container: '#related-products',
  objectIDs: ['product-123'],
  limit: 4,
  templates: {
    item: (item, { html }) => html`
      <article>
        <img src="${item.image}" />
        <h3>${item.name}</h3>
      </article>
    `,
  },
})

frequentlyBoughtTogether

Show products frequently bought together:

import { frequentlyBoughtTogether } from 'instantsearch.js/es/widgets';

frequentlyBoughtTogether({
  container: '#frequently-bought-together',
  objectIDs: ['product-123'],
  limit: 4,
  templates: {
    item: (item, { html }) => html`
      <article>
        <img src="${item.image}" />
        <h3>${item.name}</h3>
      </article>
    `,
  },
})

Next Steps

Customization

Customize templates and create custom widgets

Styling

Style your search interface with CSS

Routing

Synchronize search state with URLs

Custom Widgets

Build your own widgets with connectors

Getting Started

Core Concepts

Vanilla JavaScript

React

Vue

Advanced Guides

​Widget API Pattern

​Search Widgets

​searchBox

​hits

​infiniteHits

​configure

​Filtering Widgets

​refinementList

​hierarchicalMenu

​menu

​rangeInput

​rangeSlider

​toggleRefinement

​ratingMenu

​numericMenu

​Refinement Management

​currentRefinements

​clearRefinements

​Navigation Widgets

​pagination

​breadcrumb

​Utility Widgets

​stats

​sortBy

​hitsPerPage

​poweredBy

​Advanced Widgets

​panel

​index

​dynamicWidgets

​AI-Powered Widgets

​chat

​filterSuggestions

​Recommendation Widgets

​trendingItems

​relatedProducts

​frequentlyBoughtTogether

​Next Steps

Customization

Styling

Routing

Custom Widgets

Build docs developers (and LLMs) love

Widget API Pattern

Search Widgets

searchBox

hits

infiniteHits

configure

Filtering Widgets

refinementList

hierarchicalMenu

menu

rangeInput

rangeSlider

toggleRefinement

ratingMenu

numericMenu

Refinement Management

currentRefinements

clearRefinements

Navigation Widgets

pagination

breadcrumb

Utility Widgets

stats

sortBy

hitsPerPage

poweredBy

Advanced Widgets

panel

index

dynamicWidgets

AI-Powered Widgets

chat

filterSuggestions

Recommendation Widgets

trendingItems

relatedProducts

frequentlyBoughtTogether

Next Steps