<p align="center">
<a href="https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/">
<img alt="InstantSearch.js" src="https://github.com/algolia/instantsearch/blob/master/.github/banner.png?raw=true">
</a>
<p align="center">
InstantSearch.js is a JavaScript library for building performant and instant search experiences with <a href="https://www.algolia.com/?utm_source=instantsearch.js&utm_campaign=repository">Algolia</a>.
</p>
</p>
<hr>
<p>InstantSearch.js is a vanilla JavaScript library that lets you create an instant-search result experience using <a href="https://www.algolia.com/?utm_source=instantsearch.js&utm_campaign=repository">Algolia</a>’s search API. It is part of the InstantSearch family:</p>
<p><strong>InstantSearch.js</strong> | <a href="https://github.com/algolia/instantsearch/">React InstantSearch</a> | <a href="https://github.com/algolia/instantsearch/">Vue InstantSearch</a> | <a href="https://github.com/algolia/instantsearch/">React InstantSearch Native</a> | <a href="https://github.com/algolia/instantsearch-android">InstantSearch Android</a> | <a href="https://github.com/algolia/instantsearch-ios">InstantSearch iOS</a></p>
<details>
<summary><strong>Table of contents</strong></summary>
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
<ul>
<li><a href="#why">Why</a></li>
<li><a href="#getting-started">Getting started</a></li>
<li><a href="#installation">Installation</a><ul>
<li><a href="#typescript-users">TypeScript users</a></li>
</ul>
</li>
<li><a href="#documentation">Documentation</a></li>
<li><a href="#demos">Demos</a></li>
<li><a href="#playground">Playground</a></li>
<li><a href="#browser-support">Browser support</a></li>
<li><a href="#troubleshooting">Troubleshooting</a></li>
<li><a href="#contributing">Contributing</a></li>
<li><a href="#license">License</a></li>
</ul>
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
</details>
<h2 id="id-why">Why</h2>
<p>You should be using InstantSearch if you want to:</p>
<ul>
<li>Design search experiences with best practices</li>
<li>Customize your components at will</li>
<li>Remain independent from external frameworks</li>
</ul>
<h2 id="id-getting-started">Getting started</h2>
<p>Using InstantSearch.js is as simple as adding this JavaScript code to your page:</p>
<pre><code class="hljs language-javascript"><span class="hljs-comment">// 1. Instantiate the search</span>
<span class="hljs-keyword">const</span> search = <span class="hljs-title function_">instantsearch</span>({
<span class="hljs-attr">indexName</span>: <span class="hljs-string">'instant_search'</span>,
<span class="hljs-attr">searchClient</span>: <span class="hljs-title function_">algoliasearch</span>(<span class="hljs-string">'latency'</span>, <span class="hljs-string">'6be0576ff61c053d5f9a3225e2a90f76'</span>),
});
search.<span class="hljs-title function_">addWidgets</span>([
<span class="hljs-comment">// 2. Create an interactive search box</span>
instantsearch.<span class="hljs-property">widgets</span>.<span class="hljs-title function_">searchBox</span>({
<span class="hljs-attr">container</span>: <span class="hljs-string">'#searchbox'</span>,
<span class="hljs-attr">placeholder</span>: <span class="hljs-string">'Search for products'</span>,
}),
<span class="hljs-comment">// 3. Plug the search results into the product container</span>
instantsearch.<span class="hljs-property">widgets</span>.<span class="hljs-title function_">hits</span>({
<span class="hljs-attr">container</span>: <span class="hljs-string">'#products'</span>,
<span class="hljs-attr">templates</span>: {
<span class="hljs-attr">item</span>: <span class="hljs-function">(<span class="hljs-params">hit, { html, components }</span>) =></span>
html`<span class="language-xml">
<span class="hljs-tag"><<span class="hljs-name">h3</span>></span></span><span class="hljs-subst">${components.Highlight({ attribute: <span class="hljs-string">'name'</span>, hit })}</span><span class="language-xml"><span class="hljs-tag"></<span class="hljs-name">h3</span>></span>
<span class="hljs-tag"><<span class="hljs-name">p</span>></span></span><span class="hljs-subst">${components.Snippet({ attribute: <span class="hljs-string">'description'</span>, hit })}</span><span class="language-xml"><span class="hljs-tag"></<span class="hljs-name">p</span>></span>
`</span>,
},
}),
<span class="hljs-comment">// 4. Make the brands refinable</span>
instantsearch.<span class="hljs-property">widgets</span>.<span class="hljs-title function_">refinementList</span>({
<span class="hljs-attr">container</span>: <span class="hljs-string">'#brand'</span>,
<span class="hljs-attr">attribute</span>: <span class="hljs-string">'brand'</span>,
}),
]);
<span class="hljs-comment">// 5. Start the search!</span>
search.<span class="hljs-title function_">start</span>();
</code></pre>
<p align="center">
<a href="https://codesandbox.io/s/github/algolia/doc-code-samples/tree/master/InstantSearch.js/getting-started" title="Edit on CodeSandbox">
<img alt="Edit on CodeSandbox" src="https://codesandbox.io/static/img/play-codesandbox.svg">
</a>
</p>
<p>To learn more about the library, follow the <a href="https://www.algolia.com/doc/guides/building-search-ui/getting-started/js/">getting started</a> guide or check how to <a href="https://www.algolia.com/doc/guides/building-search-ui/installation/js/">add it to your own project</a>.</p>
<h2 id="id-installation">Installation</h2>
<pre><code class="hljs language-sh">npm install instantsearch.js algoliasearch
<span class="hljs-comment"># or</span>
yarn add instantsearch.js algoliasearch
</code></pre>
<h3 id="id-typescript-users">TypeScript users</h3>
<p>To use InstantSearch.js in a TypeScript environment, depending on your <a href="https://github.com/algolia/algoliasearch-client-javascript"><code>algoliasearch</code></a> version, you need to import different types.</p>
<blockquote>
<p>You still need to import these types even if you don't use InstantSearch.js with <a href="https://github.com/algolia/algoliasearch-client-javascript"><code>algoliasearch</code></a>.</p>
</blockquote>
<h4 id="id-algoliasearch-v4x"><code>algoliasearch</code> v4.x</h4>
<p>This version uses types provided by both <code>algoliasearch</code> and <code>@algolia/client-search</code>.</p>
<pre><code class="hljs language-bash">yarn add algoliasearch@4 @algolia/client-search
</code></pre>
<h4 id="id-algoliasearch-v3x"><code>algoliasearch</code> v3.x</h4>
<pre><code class="hljs language-bash">yarn add @types/algoliasearch@3
</code></pre>
<blockquote>
<p>v3.x is deprecated and will soon no longer be supported.</p>
</blockquote>
<h2 id="id-documentation">Documentation</h2>
<p>The documentation is available on the <a href="https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/">Algolia website</a>.</p>
<h2 id="id-demos">Demos</h2>
<div class="table-responsive"><table class="table table-striped"><tr>
<th>E-commerce</th>
<th>Media</th>
<th>Travel</th>
</tr>
<tr>
<td><a href="https://instantsearchjs.netlify.app/examples/e-commerce/"><img src="https://www.algolia.com/doc/assets/images/build-search-ui/demos/e-commerce-2c7ed6b6.png" width="250" alt="E-commerce demo preview"></a></td>
<td><a href="https://instantsearchjs.netlify.app/examples/media/"><img src="https://www.algolia.com/doc/assets/images/build-search-ui/demos/media-articles-abc153ab.png" width="250" alt="Media demo preview"></a></td>
<td><a href="https://instantsearchjs.netlify.app/examples/tourism/"><img src="https://instantsearchjs.netlify.app/examples/tourism/capture.png" width="250" alt="Tourism demo preview"></a></td>
</tr>
</table></div><p>See more demos <a href="https://www.algolia.com/doc/guides/building-search-ui/resources/demos/js/">on the website</a>.</p>
<h2 id="id-playground">Playground</h2>
<p>You can get to know InstantSearch.js on <a href="https://codesandbox.io/s/github/algolia/create-instantsearch-app/tree/templates/instantsearch.js">this playground</a>.</p>
<p>Start by <a href="https://www.algolia.com/doc/guides/building-search-ui/widgets/showcase/js/">adding widgets</a> and tweaking the display. Once you feel familiar with the library, we recommend following the <a href="https://www.algolia.com/doc/guides/building-search-ui/getting-started/js/">getting started guide</a>.</p>
<h2 id="id-browser-support">Browser support</h2>
<p>We support the <strong>last two versions of major browsers</strong> (Chrome, Edge, Firefox, Safari).</p>
<p>Please refer to the <a href="https://www.algolia.com/doc/guides/building-search-ui/installation/js/#browser-support">browser support</a> section in the documentation to use InstantSearch.js on other browsers.</p>
<h2 id="id-troubleshooting">Troubleshooting</h2>
<p>Encountering an issue? Before reaching out to support, we recommend heading to our <a href="https://www.algolia.com/doc/guides/building-search-ui/troubleshooting/faq/js/">FAQ</a> where you will find answers for the most common issues and gotchas with the library.</p>
<h2 id="id-contributing">Contributing</h2>
<p>We welcome all contributors, from casual to regular 💙</p>
<ul>
<li><strong>Bug report</strong>. Is something not working as expected? <a href="https://github.com/algolia/instantsearch/issues/new?template=BUG_REPORT.yml&labels=triage,Library%3A%20InstantSearch.js">Send a bug report</a>.</li>
<li><strong>Feature request</strong>. Would you like to add something to the library? <a href="https://github.com/algolia/instantsearch/discussions/new?category=ideas&labels=triage,Library%3A%20InstantSearch.js&title=Feature%20request%3A%20">Send a feature request</a>.</li>
<li><strong>Documentation</strong>. Did you find a typo in the doc? <a href="https://github.com/algolia/instantsearch/issues/new?labels=triage,Library%3A%20InstantSearch.js">Open an issue</a> and we'll take care of it.</li>
<li><strong>Development</strong>. If you don't know where to start, you can check the open issues that are <a href="https://github.com/algolia/instantsearch/issues?q=is%3Aopen+is%3Aissue+label%3A%22Difficulty%3A+Easy%22+label%3A%22Library%3A%20InstantSearch.js%22">tagged easy</a>, the <a href="https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug%22+label%3A%22Library%3A%20InstantSearch.js%22">bugs</a> or <a href="https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Chore%22+label%3A%22Library%3A%20InstantSearch.js%22">chores</a>.</li>
</ul>
<p>To start contributing to code, you need to:</p>
<ol>
<li><a href="https://help.github.com/articles/fork-a-repo/">Fork the project</a></li>
<li><a href="https://help.github.com/articles/cloning-a-repository/">Clone the repository</a></li>
<li>Install the dependencies: <code>yarn</code></li>
<li>Run the development mode: <code>yarn storybook</code></li>
<li><a href="http://localhost:6006">Open the stories</a></li>
</ol>
<p>Please read <a href="https://github.com/algolia/instantsearch/blob/master/CONTRIBUTING.md">our contribution process</a> to learn more.</p>
<h2 id="id-license">License</h2>
<p>InstantSearch.js is <a href="LICENSE">MIT licensed</a>.</p>
<!-- Links -->