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/.
- Setup
- Quick Start
- Browser support
- Instant search configuration
- Development workflow
- Test
- Functional tests
- License
- Contributing
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>We recommend using jsDelivr, but algoliasearch is also available at:
- CDNJS: https://cdnjs.com/libraries/instantsearch.js
- npmcdn:
Using jsDelivr you will get auto updates for all the 1.x.x versions without any breaking change.
npm install instantsearch.js --savevar 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: { // optional, 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();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.
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 optional attributes to enable other features.
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'
});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'
}
});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: {}
});Only the local example:
npm run dev
# open http://localhost:8080
# make changes in your widgets, or in example/app.jsLocal example and docs:
npm run dev:docs
# open http://localhost:4000/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 CanaryMost of the time npm run test:watch is sufficient.
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.1aThen run functional tests dev command with auto reload:
npm run test:functional:devYou 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-serverUseful when you want to modify the functional test app.
Your docker installation must be compatible and ready to make the --net="host" works.
instantsearch.js is MIT licensed.
We have a contributing guide, join us!