What is InstantSearch.js?

InstantSearch.js is an open source UI library for Vanilla JS that lets you build a search interface in your frontend app.

InstantSearch focuses on enhancing your frontend with widgets that you can combine to create unique search interfaces.

InstantSearch suite includes various “flavors” to meet different development needs:

InstantSearch offers three levels of increasing control over your UI:

1. Start with a predefined widget that you can configure and style with CSS.
2. To change its render output (DOM or Native), customize a predefined widget to render what you want.
3. To implement something that doesn’t exist, create a custom widget.

Predefined widgets

The recommended way to use InstantSearch is with its predefined widgets such as searchBox. InstantSearch includes a set of widgets that are most often used in search experiences. Widgets provide features and a rendered output. You can place them anywhere on your UI, configure them, and style them with CSS.

For example, add the refinementList` widget and ask it to show a list of brands, so your users can refine their search using those brands.

1
2
3
4
instantsearch.widgets.refinementList({
  container: document.querySelector('#brand'),
  attribute: 'brand',
});

The InstantSearch wrapper

The instantsearch wrapper communicates between your app and Algolia. This is where you add all the widgets. It accepts a search client and an index name.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
const searchClient = algoliasearch(
  'latency',
  '6be0576ff61c053d5f9a3225e2a90f76'
);

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

search.addWidgets([
  instantsearch.widgets.refinementList({
    container: document.querySelector('#brand'),
    attribute: 'brand',
  })
]);

Once you’ve added all the desired widgets to the wrapper, call the start method to begin searching:

1
search.start();

For more information, see InstantSearch.js API reference and Getting started.

CSS theme

The predefined widgets in InstantSearch.js are compatible with the default CSS theme:

For more information, see Style your widgets.

Customize widgets

Algolia’s predefined widgets, with their fixed behavior and output, may not fully meet your requirements. For example, you might want to customize the rendering of the menu widget to display as a select element instead of a list of links. You may also want to render it as a keyboard-controlled slideshow of images.

To address these limitations, InstantSearch.js uses “connectors” to redefine widget behavior and DOM output.

For more information, see Customize an InstantSearch.js widget.

Custom widgets

If none of the previous solutions work for you and you want to create a new widget from scratch, InstantSearch provides a third API layer of API for this: creating custom widgets. This requires two APIs: the first one lets you create a new connector, and the second one lets you create a new widget. Both solutions give you full control of the render and behavior.

When building a new widget, be prepared to dive deep into the Algolia semantics to achieve what you want.

For more information, see Create your own InstantSearch.js widgets.

Need help?

InstantSearch.js is worked on full-time by Algolia’s JavaScript team.

Join the community

Ask questions and find answers on those following platforms.

• Algolia Community Discord
• Stack Overflow
• Open and read GitHub issues

Provide feedback

• Write a feature request
• Use the Did you find this page helpful? form below

Stay up to date

• Look at the changelog.

Contributing?

All contributors are welcome, from casual to regular. Feel free to open a pull request.