Skip to main content
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.
View demo

Explore related content in the Algolia Academy

InstantSearch
 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.
JavaScript
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.
JavaScript
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:
JavaScript
search.start();

​
CSS theme

The predefined widgets in InstantSearch.js are compatible with the default CSS theme: Theme preview 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.

​
Resources

Use the following links and resources to learn more.

​
See also

​
Join the community

Ask questions and find answers on the following platforms:
⌘I