Skip to main content
algoliasearch-helper is the low-level library that powers InstantSearch. It provides a programmatic API for managing search state, performing searches, and handling results. Most developers use InstantSearch.js, but the helper is useful for advanced customization or building custom search UIs.

​
Installation

npm install algoliasearch-helper algoliasearch

​
Basic Usage

import algoliasearch from 'algoliasearch';
import algoliasearchHelper from 'algoliasearch-helper';

const client = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

const helper = algoliasearchHelper(client, 'products', {
  facets: ['brand', 'category'],
  disjunctiveFacets: ['color'],
  hitsPerPage: 20,
});

helper.on('result', (event) => {
  console.log('Results:', event.results);
});

helper.search();

​
AlgoliaSearchHelper

The main helper class for managing search.

​
Constructor

algoliasearchHelper(client, indexName, options)
​
client
SearchClient
required
Algolia search client instance.
import algoliasearch from 'algoliasearch';
const client = algoliasearch('APP_ID', 'API_KEY');
​
indexName
string
required
Name of the Algolia index to search.
​
options
PlainSearchParameters
Initial search parameters.
{
  query: 'phone',
  facets: ['brand'],
  hitsPerPage: 20,
}

​
Properties

​
state
SearchParameters
Current search state (immutable).
console.log(helper.state.query);
console.log(helper.state.facets);
​
lastResults
SearchResults | null
Results from the last search.
if (helper.lastResults) {
  console.log(helper.lastResults.hits);
}
​
derivedHelpers
DerivedHelper[]
Array of derived helpers (used internally by InstantSearch for multi-index).

​
Methods

Trigger a search with current state. 
helper.search();

​
setQuery(query)

Set the search query. 
helper.setQuery('laptop').search();

​
setPage(page)

Set the current page (zero-based). 
helper.setPage(2).search();

​
addFacet(facetName)

Add a facet to the search. 
helper.addFacet('brand').search();

​
removeFacet(facetName)

Remove a facet from the search. 
helper.removeFacet('brand').search();

​
addFacetRefinement(facet, value)

Add a facet filter. 
helper.addFacetRefinement('brand', 'Apple').search();

​
removeFacetRefinement(facet, value)

Remove a facet filter. 
helper.removeFacetRefinement('brand', 'Apple').search();

​
toggleFacetRefinement(facet, value)

Toggle a facet filter on/off. 
helper.toggleFacetRefinement('brand', 'Apple').search();

​
clearRefinements()

Clear all refinements. 
helper.clearRefinements().search();

​
setState(newState)

Set a new search state. 
const newState = helper.state.setQuery('phone').setPage(0);
helper.setState(newState).search();

​
Events

The helper is an event emitter with these events:

​
result

Fired when search results are received. 
helper.on('result', (event) => {
  console.log('Results:', event.results);
  console.log('State:', event.state);
});

​
error

Fired when a search error occurs. 
helper.on('error', (event) => {
  console.error('Search error:', event.error);
});

​
search

Fired when a search is triggered. 
helper.on('search', (event) => {
  console.log('Searching with state:', event.state);
});

​
change

Fired when the search state changes. 
helper.on('change', (event) => {
  console.log('State changed:', event.state);
  console.log('Results:', event.results);
  console.log('Page reset:', event.isPageReset);
});

​
SearchParameters

Immutable search parameters object.

​
Common Parameters

const params = helper.state
  .setQuery('laptop')
  .setPage(0)
  .setHitsPerPage(20)
  .addFacet('brand')
  .addFacetRefinement('brand', 'Apple')
  .addNumericRefinement('price', '>=', 100)
  .addNumericRefinement('price', '<=', 1000);

helper.setState(params).search();

​
Methods

​
setQuery(query)
string
Set search query.
​
setPage(page)
number
Set page number (zero-based).
​
setHitsPerPage(n)
number
Set number of hits per page.
​
addFacet(facet)
string
Add a facet.
​
removeFacet(facet)
string
Remove a facet.
​
addFacetRefinement(facet, value)
string, string
Add facet refinement.
​
addNumericRefinement(attribute, operator, value)
string, string, number
Add numeric refinement (operators: <, <=, =, !=, >=, >).

​
SearchResults

Search results wrapper with helper methods.

​
Properties

​
hits
Array
Array of search result hits.
helper.lastResults.hits.forEach(hit => {
  console.log(hit.objectID, hit.name);
});
​
nbHits
number
Total number of hits.
​
page
number
Current page number.
​
nbPages
number
Total number of pages.
​
hitsPerPage
number
Number of hits per page.
​
query
string
Current search query.
​
facets
Array
Facet values and counts.
helper.lastResults.facets.forEach(facet => {
  console.log(facet.name, facet.data);
});

​
Examples

import algoliasearch from 'algoliasearch';
import algoliasearchHelper from 'algoliasearch-helper';

const client = algoliasearch('APP_ID', 'API_KEY');
const helper = algoliasearchHelper(client, 'products');

helper.on('result', ({ results }) => {
  console.log(`Found ${results.nbHits} results`);
  results.hits.forEach(hit => {
    console.log(hit.name);
  });
});

helper.setQuery('laptop').search();

const helper = algoliasearchHelper(client, 'products', {
  facets: ['brand', 'category'],
  disjunctiveFacets: ['color'],
});

helper.on('result', ({ results }) => {
  // Display facet counts
  const brandFacet = results.getFacetByName('brand');
  console.log('Brands:', brandFacet.data);
});

// Add refinements
helper
  .addFacetRefinement('brand', 'Apple')
  .addFacetRefinement('category', 'Laptops')
  .search();

​
Numeric Filtering

const helper = algoliasearchHelper(client, 'products');

// Price range: $100 - $1000
helper
  .addNumericRefinement('price', '>=', 100)
  .addNumericRefinement('price', '<=', 1000)
  .search();

​
Pagination

const helper = algoliasearchHelper(client, 'products', {
  hitsPerPage: 20,
});

helper.on('result', ({ results }) => {
  console.log(`Page ${results.page + 1} of ${results.nbPages}`);
  
  // Next page
  document.querySelector('#next').onclick = () => {
    helper.setPage(results.page + 1).search();
  };
  
  // Previous page
  document.querySelector('#prev').onclick = () => {
    helper.setPage(results.page - 1).search();
  };
});

helper.search();

​
Multiple Indices

const productsHelper = algoliasearchHelper(client, 'products');
const articlesHelper = algoliasearchHelper(client, 'articles');

productsHelper.on('result', ({ results }) => {
  console.log('Products:', results.hits);
});

articlesHelper.on('result', ({ results }) => {
  console.log('Articles:', results.hits);
});

// Search both indices
const query = 'phone';
productsHelper.setQuery(query).search();
articlesHelper.setQuery(query).search();

const helper = algoliasearchHelper(client, 'stores');

// Search around a location (lat, lng, radius in meters)
const params = helper.state
  .setQueryParameter('aroundLatLng', '40.71,-74.01')
  .setQueryParameter('aroundRadius', 5000);

helper.setState(params).search();

​
Custom Event Handling

const helper = algoliasearchHelper(client, 'products');

helper.on('search', ({ state }) => {
  console.log('Searching...', state.query);
  showLoadingIndicator();
});

helper.on('result', ({ results }) => {
  hideLoadingIndicator();
  renderResults(results.hits);
});

helper.on('error', ({ error }) => {
  hideLoadingIndicator();
  showError(error.message);
});

helper.setQuery('laptop').search();

​
When to Use algoliasearch-helper

Use InstantSearch.js for most cases: InstantSearch.js provides a higher-level API with UI widgets. Use algoliasearch-helper only when you need direct control over search logic.
Use algoliasearch-helper when:
  • Building a custom search UI without InstantSearch widgets
  • Implementing complex search logic not supported by InstantSearch
  • Integrating search into non-standard UI frameworks
  • Building a search SDK for another framework

​
TypeScript Support

algoliasearch-helper includes TypeScript type definitions: 
import algoliasearchHelper, {
  AlgoliaSearchHelper,
  SearchParameters,
  SearchResults,
  PlainSearchParameters,
} from 'algoliasearch-helper';

const helper: AlgoliaSearchHelper = algoliasearchHelper(
  client,
  'products',
  {
    facets: ['brand'],
  }
);

helper.on('result', ({ results }: { results: SearchResults }) => {
  console.log(results.hits);
});