Skip to main content

​
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
View demoView source code
1

Add starter code

To generate some starter code, use the create-instantsearch-app tool. It provides the index data, all necessary code, and predefined credentials (application ID and API key).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 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: 
    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. Search box with results and pagination in the quickstart app
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;
}
  2. In your browser, after a page refresh, the layout includes a set of brand filters. Search UI with a Brands filter in the quickstart app
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.Search UI with product images in the quickstart app

​
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 query.
  • 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