instantsearch.js is a library of widgets to build high performance instant search experiences using Algolia
API is unstable. We welcome any idea and pull request.
To get started, check out algolia.github.com/instantsearch.js!
- Setup
- Quick Start
- Browser support
- Development workflow
- Test
- Instant search configuration
- License
- More...
instantsearch.js is available on jsDelivr:
<link rel="stylesheet" type="text/css" href="//cdn.jsdelivr.net/instantsearch.js/0/instantsearch.min.css" />
<script src="//cdn.jsdelivr.net/instantsearch.js/0/instantsearch.min.js"></script>npm install instantsearch.js --save-devvar instantsearch = require('instantsearch.js');
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 search box 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.
npm run dev
# open http://localhost:8080
# make changes in your widgets, or in example/app.jsnpm test # jsdom + lint
npm run test:watch # jsdom
npm run test:watch:browser # chrome
npm run test:watch:browser -- --browsers ChromeCanary # force Chrome CanaryThe 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.
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: {}
});instantsearch.js is MIT licensed.
There's only so much we can cram in here. To read more about the community and guidelines for submitting pull requests, please read the Contributing document.