Skip to main content
InstantSearch.js is a vanilla JavaScript library that lets you create a search results experience with Algolia. This tutorial generates code to:
  • Display and format the search box and results
  • Use pre-built UI components (widgets) to filter results
View demoView source code

​
Before you begin

This tutorial assumes you have JavaScript knowledge and have installed InstantSearch.js.

​
Tutorial

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

​
Add starter code

To generate some starter code, use the create-instantsearch-app installed with InstantSearch.js. In a terminal, paste: 
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 generates 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
create-instantsearch-app provides the index data, all necessary code, and predefined credentials (application ID and API key).

​
Add the search user interface code

Open the file index.html, remove the header, and replace the div.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>
Open the file src/app.css and replace its content with:
CSS
body {
  font-family: sans-serif;
  padding: 1em;
}
.ais-SearchBox {
  margin: 1em 0;
}

​
Understand the code

In src/app.js, you’ll see several InstantSearch widgets:
  • instantsearch is the root InstantSearch.js component. All other widgets must be wrapped within this widget
  • searchBox displays a search box for users to type queries into
  • hits displays the results from Algolia, based on the query
  • pagination implements paging logic.

​
Run your project

In your terminal, type: 
cd ais-ecommerce-demo-app
npm start
Open your browser and go to http://localhost:3000. You’ll see this: Getting started 1

​
Add more widgets

To enhance your search UI, add these widgets: Open `index.html and update it:
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>
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,
  }),
]);

​
Alter the styling

The widgets have a predefined style but this can be altered. To create a two-column layout, open src/app.css and update it:
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;
}
In your browser, after a page refresh, you’ll see this: Getting started 2

​
Customize hits

Open the file 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>
      `,
    },
  }),
]);

​
Add formatting

Open the file 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 this: Getting started 3 For more information about customization, see Customize an existing widget.

​
Configure the dataset

First:
  1. Download the dataset
  2. Set up an API client and send your data to Algolia
  3. Configure the index with the following code:
$index->setSettings(array(
  "searchableAttributes" => [
    "brand",
    "name",
    "categories",
    "unordered(description)"
  ],
  "customRanking" => [
    "desc(popularity)"
  ],
  "attributesForFaceting" => [
    "searchable(brand)",
    "type",
    "categories",
    "price"
  ]
));
⌘I