Guides / Building Search UI

Jan 15, 2025

Getting started with InstantSearch.js

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:

Copy
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:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
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:

Copy
<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:

Copy
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:

Copy

1
2
cd ais-ecommerce-demo-app
npm start

Open your browser and go to http://localhost:3000.

You’ll see this:

Add more widgets

To enhance your search UI, add these widgets:

clearRefinements displays a button to clear the current refinements
refinementList displays a list of brands to filter the search
configure passes search parameters. In this example, it sets the hitsPerPage to 8. It doesn’t render anything to the DOM itself.

Open `index.html and update it:

Copy
<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:

Copy
// 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:

Copy
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:

Customize hits

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

Copy
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:

Copy
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:

For more information about customization, see Customize an existing widget.

Configure the dataset

First:

Download the dataset
Set up an API client and send your data to Algolia
Configure the index with the following code:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
$index->setSettings(array(
  "searchableAttributes" => [
    "brand",
    "name",
    "categories",
    "unordered(description)"
  ],
  "customRanking" => [
    "desc(popularity)"
  ],
  "attributesForFaceting" => [
    "searchable(brand)",
    "type",
    "categories",
    "price"
  ]
));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
index.set_settings(
  searchableAttributes: [
    'brand',
    'name',
    'categories',
    'unordered(description)'
  ],
  customRanking: [
    'desc(popularity)'
  ],
  attributesForFaceting: [
    'searchable(brand)',
    'type',
    'categories',
    'price'
  ]
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
index.setSettings({
   searchableAttributes: [
    'brand',
    'name',
    'categories',
    'unordered(description)'
  ],
  customRanking: [
    'desc(popularity)'
  ],
  attributesForFaceting: [
    'searchable(brand)',
    'type',
    'categories',
    'price'
  ]
}).then(() => {
  // done
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
index.set_settings({
    'searchableAttributes': [
        'brand',
        'name',
        'categories',
        'unordered(description)'
    ],
    'customRanking': [
        'desc(popularity)'
    ],
    'attributesForFaceting': [
        'searchable(brand)',
        'type',
        'categories',
        'price'
    ]
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
index.setSettings([
  "searchableAttributes": [
  "brand",
  "name",
  "categories",
  "unordered(description)"
  ],
  "customRanking": [
    "desc(popularity)"
  ],
  "attributesForFaceting": [
    "searchable(brand)",
    "type",
    "categories",
    "price"
  ]
])

1
2
3
4
5
6
7
8
IndexSettings settings = new IndexSettings
{
    SearchableAttributes = new List<string> {"brand", "name", "categories", "description"},
    CustomRanking = new List<string> {"desc(popularity)"},
    UnretrievableAttributes = new List<string> {"searchable(brand)", "type", "categories", "price"}
};

index.SetSettings(settings);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
index.setSettings(
  new IndexSettings().setSearchableAttributes(Arrays.asList(
    "brand",
    "name",
    "categories",
    "unordered(description)"
  )).setCustomRanking(Arrays.asList(
    "desc(popularity)"
  )).setAttributesForFaceting(Arrays.asList(
    "searchable(brand)",
    "type",
    "categories",
    "price"
  ))
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
res, err := index.SetSettings(search.Settings{
  SearchableAttributes: opt.SearchableAttributes(
    "brand",
    "name",
    "categories",
    "unordered(description)",
  ),
  CustomRanking: opt.CustomRanking(
    "desc(popularity)",
  ),
  AttributesForFaceting: opt.AttributesForFaceting(
    "searchable(brand)",
    "type",
    "categories",
    "price",
  ),
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
val result: Future[Task] = client.execute {
    setSettings of "myIndex" `with` IndexSettings(
      searchableAttributes = Some(Seq(
        SearchableAttributes.attribute("brand"),
        SearchableAttributes.attribute("name"),
        SearchableAttributes.attribute("categories"),
        SearchableAttributes.unordered("description")
      )),
      customRanking = Some(Seq(
        CustomRanking.desc("popularity")
      )),
      attributesForFaceting = Some(Seq(
        "searchable(brand)",
        "type",
        "categories",
        "price"
      ))
    )
  }

Installation

Click and conversion events

Did you find this page helpful?

Getting started with InstantSearch.js

On this page

Before you begin

Tutorial

Add starter code

Add the search user interface code

Understand the code

Run your project

Add more widgets

Alter the styling

Customize hits

Add formatting

Configure the dataset

On this page