Get started with InstantSearch.js

Use InstantSearch.js to create a dynamic, filterable search UI.

Before you begin

This quickstart requires:

• Basic JavaScript knowledge.
• Node.js version 16 or later with npm version 5.2 or later.

Quickstart

In this quickstart, you’ll add an Algolia search interface to some starter code. The code:

• Displays and formats a search box and results
• Uses InstantSearch’s pre-built UI components (widgets) to filter results

Open CodeSandbox

Run and edit the InstantSearch.js quickstart example in CodeSandbox.

Explore source code

Browse the source for the InstantSearch.js quickstart example on GitHub.

1. Add starter code

   To generate some starter code, use the create-instantsearch-app tool. It provides the data, all necessary code, and predefined credentials ( and ).

   In a terminal, paste:

   Command line

   npx create-instantsearch-app@latest ais-ecommerce-demo-app \
     --template "InstantSearch.js" \
     --app-id "B1G2GM9NG0" \
     --api-key "aadef574be1f9252bb48d4ea09b5cfe5" \
     --index-name demo_ecommerce \
     --attributes-to-display name \
     --attributes-for-faceting ''
   

   This command creates a folder structure on your machine:

   ais-ecommerce-demo-app/
   ├── node_modules
   ├── src
   │   ├── app.css
   │   └── app.js
   ├── .editorconfig
   ├── .eslintignore
   ├── .eslintrc.js
   ├── .gitignore
   ├── .prettierrc
   ├── favicon.png
   ├── index.html
   ├── package.json
   └── README.md
   
2. Add the search UI

   1. In index.html, remove the <header>, and replace <div class="container"> with:

      HTML

      <div class="ais-InstantSearch">
        <h1>InstantSearch.js e-commerce demo</h1>
      
        <div class="right-panel">
          <div id="searchbox"></div>
          <div id="hits"></div>
          <div id="pagination"></div>
        </div>
      </div>
      

   2. Open src/app.css and replace its content with:

   CSS

           body {
             font-family: sans-serif;
             padding: 1em;
           }
           .ais-SearchBox {
             margin: 1em 0;
           }
   
3. Run the app

   1. In your terminal, type:

      Command line

      cd ais-ecommerce-demo-app
      npm start
      

   2. Open your browser and go to http://localhost:3000. The app displays the search box, results, and pagination components.

      
4. Add filters and settings

   1. Open index.html and update it to:

      HTML

      <div class="ais-InstantSearch">
        <h1>InstantSearch.js e-commerce demo</h1>
      
        <div class="left-panel">
          <div id="clear-refinements"></div>
      
          <h2>Brands</h2>
          <div id="brand-list"></div>
        </div>
      
        <div class="right-panel">
          <div id="searchbox"></div>
          <div id="hits"></div>
          <div id="pagination"></div>
        </div>
      </div>
      

   2. Open src/app.js, and add widgets to these placeholders:

      JavaScript

      // Before `search.start()`
      search.addWidgets([
        instantsearch.widgets.clearRefinements({
          container: "#clear-refinements",
        }),
      
        instantsearch.widgets.refinementList({
          container: "#brand-list",
          attribute: "brand",
        }),
      
        instantsearch.widgets.configure({
          hitsPerPage: 8,
        }),
      ]);
      
5. Create a two-column layout

   The widgets come with a predefined style but you can customize it.

   1. Open src/app.css and update it to the following to apply a two-column layout:

   CSS

             body {
               font-family: sans-serif;
               padding: 1em;
             }
             .ais-SearchBox {
               margin: 1em 0;
             }
             .ais-Pagination {
               margin-top: 1em;
             }
             .left-panel {
               float: left;
               margin-top: 1em;
               width: 250px;
             }
             .right-panel {
               margin-left: 260px;
             }
   

   1. In your browser, after a page refresh, the layout includes a Brands .

      
6. Format search results

   Open the src/app.js and replace the content of the hits widget with:

   JavaScript

   search.addWidgets([
     instantsearch.widgets.hits({
       container: "#hits",
       templates: {
         item: (hit, { html, components }) => html`
           <div>
             <img src="${hit.image}" align="left" alt="${hit.name}" />
             <div class="hit-name">
               ${components.Highlight({ hit, attribute: "name" })}
             </div>
             <div class="hit-description">
               ${components.Highlight({ hit, attribute: "description" })}
             </div>
             <div class="hit-price">$${hit.price}</div>
           </div>
         `,
       },
     }),
   ]);
   
7. Refine the styling

   1. Open src/app.css and replace its content with:

   CSS

           body {
             font-family: sans-serif;
             padding: 1em;
           }
           .ais-SearchBox {
             margin: 1em 0;
           }
           .ais-Pagination {
             margin-top: 1em;
           }
           .left-panel {
             float: left;
             margin-top: 1em;
             width: 250px;
           }
           .right-panel {
             margin-left: 260px;
           }
           .ais-InstantSearch {
             max-width: 960px;
             margin: 0 auto;
           }
           .ais-Hits-list {
             display: grid;
             grid-template-columns: repeat(2, 1fr);
             grid-gap: 1em;
           }
           .ais-Hits-item img {
             margin-right: 1em;
           }
           .hit-name {
             margin-bottom: 0.5em;
           }
           .hit-description {
             color: #888;
             font-size: 14px;
             margin-bottom: 0.5em;
           }
   

   In your browser, after a page refresh, you’ll see product images.

   

The widgets

This quickstart uses several InstantSearch widgets:

• instantsearch is the root InstantSearch.js component. You must wrap all other widgets inside this component.
• searchBox displays a search box for users to type queries into.
• hits displays the results from Algolia, based on the .
• pagination adds navigation controls to browse through pages of results.
• clearRefinements displays a button that clears the current refinements.
• refinementList displays a list of brands that users can use to filter the search.
• configure passes search parameters. In this quickstart, it sets hitsPerPage to 8.

Next steps

Instead of the credentials from create-instantsearch-app, use your own Algolia credentials.

You can send your own data or a sample dataset to Algolia using the JavaScript API client that comes preinstalled with create-instantsearch-app.

Then, configure the index with the JavaScript API client. For example, to configure the sample dataset, use the following code:

JavaScript

index
  .setSettings({
    searchableAttributes: [
      "brand",
      "name",
      "categories",
      "unordered(description)",
    ],
    customRanking: ["desc(popularity)"],
    attributesForFaceting: ["searchable(brand)", "type", "categories", "price"],
  })
  .then(() => {
    // done
  });

See also

• What is InstantSearch?
• Send and update your data
• InstantSearch widgets
• Customize an existing widget
• Send click and conversion events