instantsearch.js

What is instantsearch.js?

instantsearch.js is a library for building performant and instant search experiences with Algolia. It provides a set of widgets and tools to create highly customizable search interfaces.

What are instantsearch.js's main functionalities?

Search Box

The search box widget allows users to input their search queries. It connects to the Algolia index and fetches results based on the user's input.

const search = instantsearch({
  indexName: 'instant_search',
  searchClient: algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey')
});

search.addWidget(
  instantsearch.widgets.searchBox({
    container: '#searchbox'
  })
);

search.start();

Hits

The hits widget displays the search results. It can be customized to show different attributes of the search results and highlight the matching parts of the query.

search.addWidget(
  instantsearch.widgets.hits({
    container: '#hits',
    templates: {
      item: '<div>{{#helpers.highlight}}{ "attribute": "name" }{{/helpers.highlight}}</div>'
    }
  })
);

Refinement List

The refinement list widget allows users to filter search results based on specific attributes, such as categories. It provides checkboxes for each attribute value.

search.addWidget(
  instantsearch.widgets.refinementList({
    container: '#refinement-list',
    attribute: 'categories'
  })
);

Pagination

The pagination widget enables users to navigate through pages of search results. It provides controls for moving to the next or previous page and jumping to specific pages.

search.addWidget(
  instantsearch.widgets.pagination({
    container: '#pagination'
  })
);

Other packages similar to instantsearch.js

react-instantsearch

react-instantsearch is a library for building Algolia search interfaces in React. It provides React components that wrap instantsearch.js widgets, making it easier to integrate with React applications. Compared to instantsearch.js, it is more suitable for React-based projects.

searchkit

searchkit is a suite of UI components built in React to create search experiences powered by Elasticsearch. It offers a similar set of features to instantsearch.js but is designed to work with Elasticsearch instead of Algolia.

README

instantsearch.js is a library of UI widgets to help you build the best instant-search experience with Algolia's Hosted Search API.

Have a look at the website: https://community.algolia.com/instantsearch.js/.

Table of contents

• Setup
  • With the jsDelivr CDN
  • With npm, browserify, webpack
• Quick Start
• Browser support
• Instant search configuration
  • Number locale
  • Initial search parameters
  • URL synchronisation
• Development workflow
• Test
• Functional tests
  • It's not working!
• License
• Contributing

Setup

With the jsDelivr CDN

instantsearch.js is available on jsDelivr:

<link rel="stylesheet" type="text/css" href="//cdn.jsdelivr.net/instantsearch.js/1/instantsearch.min.css" />
<script src="//cdn.jsdelivr.net/instantsearch.js/1/instantsearch.min.js"></script>

Other CDNS

We recommend using jsDelivr, but algoliasearch is also available at:

• CDNJS: https://cdnjs.com/libraries/instantsearch.js
• npmcdn:
  • https://npmcdn.com/instantsearch.js@1/dist/instantsearch.min.js
  • https://npmcdn.com/instantsearch.js@1/dist/instantsearch.min.css

Using jsDelivr you will get auto updates for all the 1.x.x versions without any breaking change.

With npm, browserify, webpack

npm install instantsearch.js --save

Quick Start

var instantsearch = require('instantsearch.js');
// or use the 'instantsearch' global variable when using the jsDelivr build

var search = instantsearch({
  appId: appId, // Mandatory
  apiKey: apiKey, // Mandatory
  indexName: indexName, // Mandatory
  numberLocale: 'fr-FR', // Optional, defaults to 'en-EN',
  urlSync: { // optionnal, activate url sync if defined
    useHash: false
  }
});

// add a searchBox widget
search.addWidget(
  instantsearch.widgets.searchBox({
    container: '#search-box',
    placeholder: 'Search for libraries in France...'
  })
);

// add a hits widget
search.addWidget(
  instantsearch.widgets.hits({
    container: '#hits-container',
    hitsPerPage: 10
  })
);

// start
search.start();

Browser support

We natively support IE10+ and all other modern browsers without any dependency need on your side.

To get < IE10 support, please insert this code in the <head>:

<meta http-equiv="X-UA-Compatible" content="IE=Edge">
<!--[if lte IE 9]>
  <script src="https://cdn.polyfill.io/v2/polyfill.min.js"></script>
<![endif]-->

We use the polyfill.io.

Instant search configuration

Also see our documentation website.

The main configuration of instantsearch.js is done through a configuration object. The minimal configuration is made a of three attributes :

instantsearch({
  appId: 'my_application_id',
  apiKey: 'my_search_api_key',
  indexName: 'my_index_name'
});

It can also contain other optionnal attributes to enable other features.

Number locale

For the display of numbers, the locale will be determined by the browsers or forced in the configuration :

instantsearch({
  appId: 'my_application_id',
  apiKey: 'my_search_api_key',
  indexName: 'my_index_name',
  numberLocale: 'en-US'
});

Initial search parameters

At the start of instantsearch, the search configuration is based on the input of each widget and the URL. It is also possible to change the defaults of the configuration through an object that can contain any parameters understood by the Algolia API.

instantsearch({
  appId: 'my_application_id',
  apiKey: 'my_search_api_key',
  indexName: 'my_index_name',
  searchParameters: {
    typoTolerance: 'strict'
  }
});

URL synchronisation

Instantsearch let you synchronize the url with the current search parameters. In order to activate this feature, you need to add the urlSync object. It accepts 3 parameters :

• trackedParameters:string[] parameters that will be synchronized in the URL. By default, it will track the query, all the refinable attribute (facets and numeric filters), the index and the page.
• useHash:boolean if set to true, the url will be hash based. Otherwise, it'll use the query parameters using the modern history API.
• threshold:number time in ms after which a new state is created in the browser history. The default value is 700.

All those parameters are optional and a minimal configuration looks like :

instantsearch({
  appId: 'my_application_id',
  apiKey: 'my_search_api_key',
  indexName: 'my_index_name',
  urlSync: {}
});

Development workflow

Only the local example:

npm run dev
# open http://localhost:8080
# make changes in your widgets, or in example/app.js

Local example and docs:

npm run dev:docs
# open http://localhost:4000/

Test

npm test # unit tests, jsdom + lint
npm run test:watch # unit tests, jsdom, watch

npm run test:browser # unit tests, chrome
npm run test:browser:watch # unit tests, chrome, watch
npm run test:browser -- --browsers ChromeCanary # force Chrome Canary

Most of the time npm run test:watch is sufficient.

Functional tests

You need docker.

Run it like so:

docker pull elgalu/selenium:2.50.1a
docker run --net="host" --privileged --name=grid -e VNC_PASSWORD=fun -e NOVNC=true elgalu/selenium:2.50.1a

Then run functional tests dev command with auto reload:

npm run test:functional:dev

You can see the live browser at http://localhost:26080/vnc.html (password: fun).

You can use the full webdriverio API: http://webdriver.io/api.html.

You can run the underlying web server for debugging purposes:

npm run test:functional:dev:debug-server

Useful when you want to modify the functional test app.

It's not working!

Your docker installation must be compatible and ready to make the --net="host" works.

License

instantsearch.js is MIT licensed.

Contributing

We have a contributing guide, join us!