How to install InstantSearch.js

Install InstantSearch.js with a packaging system, with a direct link in your web page, or with create-instantsearch-app.

With a packaging system

If you have a JavaScript build tool, you can install InstantSearch.js from npm:

1
npm install algoliasearch instantsearch.js

Then in your module, you can load the main package:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// Import InstantSearch.js
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import instantsearch from 'instantsearch.js';
import { searchBox, hits } from 'instantsearch.js/es/widgets';

/*
  Initialize the search client
  
  If you're logged into the Algolia dashboard, the following values for
  YourApplicationID and YourSearchOnlyAPIKey are auto-selected from
  the currently selected Algolia application.
*/
const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

// Render the InstantSearch.js wrapper
// Replace INDEX_NAME with the name of your index.
const search = instantsearch({
  indexName: 'INDEX_NAME',
  searchClient,
});

search.addWidgets([
  searchBox({
    container: "#searchbox"
  }),

  hits({
    container: "#hits"
  })
]);

search.start();

instantsearch is the root InstantSearch.js component. All widgets must be wrapped within it

In a production environment, secure your API keys as environment variables.

Directly in your page

This method uses the version of InstantSearch.js from the jsDelivr CDN:

1
2
<script src="https://cdn.jsdelivr.net/npm/algoliasearch@5.21.0/dist/lite/builds/browser.umd.js" integrity="sha256-2V0fpY1UoptnHxJ0NjqUtZqz3Pg3kcj7os54FDmWc9c=" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/instantsearch.js@4.78.0/dist/instantsearch.production.min.js" integrity="sha256-TgmjIYtuCzPUUGlHWyK8k1xVPlvPHUAGU7gLz8jwIi0=" crossorigin="anonymous"></script>

You then have access to the instantsearch function in the global scope (window).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
/*
  Initialize the search client

  If you're logged into the Algolia dashboard, the following values for
  YourApplicationID and YourSearchOnlyAPIKey are auto-selected from
  the currently selected Algolia application.
*/
const { liteClient: algoliasearch } = window['algoliasearch/lite'];
const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

// Render the InstantSearch.js wrapper
// Replace INDEX_NAME with the name of your index.
const search = instantsearch({
  indexName: 'INDEX_NAME',
  searchClient,
});

search.addWidgets([
  instantsearch.widgets.searchBox({
    container: '#searchbox',
  }),

  instantsearch.widgets.hits({
    container: '#hits',
  })
]);

search.start();

instantsearch is the root InstantSearch.js component. All widgets must be wrapped within it

In a production environment, secure your API keys as environment variables.

Load the styles

You need to manually load the companion CSS file into your page:

1
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/instantsearch.css@8.5.1/themes/reset-min.css" integrity="sha256-KvFgFCzgqSErAPu6y9gz/AhZAvzK48VJASu3DpNLCEQ=" crossorigin="anonymous">

Or you can load the satellite theme widget styles into your page.

1
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/instantsearch.css@8.5.1/themes/satellite-min.css" integrity="sha256-woeV7a4SRDsjDc395qjBJ4+ZhDdFn8AqswN1rlTO64E=" crossorigin="anonymous">

With create-instantsearch-app

Use create-instantsearch-app to create a working InstantSearch app. Similar to other interactive command-line applications, run it with npm or yarn:

1
2
3
npx create-instantsearch-app@latest 'getting-started'
# or
yarn create instantsearch-app 'getting-started'

To launch the app, type inside your terminal:

1
2
cd getting-started
npm start # or yarn start

Send click and conversion events

Capturing real-time user interactions as events gives you actionable insights via click and conversion metrics, and they help you increase your customer engagement and conversions. Events are used to activate Algolia features and products like NeuralSearch, Dynamic Re-Ranking, Query Categorization, Recommend, and Personalization.

To send click and conversion events when users interact with your search UI, set the insights option to true.

Browser support

Algolia supports the last two versions of the major browsers: Chrome, Edge, Firefox, Safari.

To support Internet Explorer 11 you need polyfills for: Array.prototype.find, Array.prototype.includes, Promise, Object.entries, and Object.assign.

The code samples in this documentation use a JavaScript syntax that isn’t natively supported by older browsers like Internet Explorer 11. If your site needs to support older browsers, use a tool like Babel to make your code work in the browsers you target.