<commit_before>---
layout: documentation
title: Documentation
permalink: /documentation/
noFooter: true
---

{::options parse_block_html="true" /}

## Introduction

<div class="shameless-marketing text-center hidden-xs">
<img src="../img/logo-instantsearch.svg" height="40" alt="logo instantsearch.js"/>
<p class="lead">Build the perfect UI with Instantsearch.js,<br>an extensive library of widgets for search experience.</p>
<p class="version">Version : {{ site.version }}</p>
<div class="spacer40"></div>
<div class="row">
<div class="col-md-4 m-b">
<div class="sticker sticker-algolia">
<img src="{{site.baseurl}}/img/logo-algolia-notext.svg" width="26"/>
</div>
Built on top of <a href="https://www.algolia.com">Algolia Search API</a>
</div>
<div class="col-md-4 m-b">
<div class="sticker sticker-open-source">
<img src="{{site.baseurl}}/img/logo-open-source.svg" width="30"/>
</div>
Driven by community and available on  <a href="http://github.com/algolia/instantsearch.js">Github</a>
</div>
<div class="col-md-4 m-b">
<div class="sticker sticker-ux">
<img src="{{site.baseurl}}/img/logo-UX.svg" width="30"/>
</div>
UI/UX Best practices
</div>
</div>
</div>

**instantsearch.js** is a JavaScript library that lets you create an instant search results page using Algolia's REST API.

Everything is about adding the meaningful widgets to compose the final search results page. Widgets are the UI components that will either deal with the input of the search (like the search bar or the facets/filters over attributes) or the output (like the actual results or some meta information about the search).

Each widget is independent and their rendering is bound to the search. They follow the **instantsearch.js** lifecycle:

  - **Configuration**: each widget add new query parameters to the underlying Algolia API client.
  - **Initial rendering**: before the initial search, the widget may update the UI.
  - **Rendering**: on each search, after the results come back from Algolia, the widgets update themselves.

The library is open-source, based on [React.js](http://facebook.github.io/react/) and hosted on GitHub: [<i class="fa fa-github"></i> algolia/instantsearch.js](https://github.com/algolia/instantsearch.js). All contributions are very welcome.

### Setup

#### From a CDN
{:.no-toc}

<div class="codebox-combo">

The fastest way to get started is to use a built version of **instantsearch.js** from a CDN:

<div class="code-box">
  <div class="code-sample-snippet ignore">
{% highlight html %}
<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>
{% endhighlight %}
  </div>
</div>

</div>

This will expose the global `instantsearch` function.

#### From NPM
{:.no-toc}

<div class="codebox-combo">

If you already have a JavaScript build system, you can use **instantsearch.js** from NPM:

<div class="code-box">
  <div class="code-sample-snippet ignore">
{% highlight sh %}
npm install instantsearch.js --save
{% endhighlight %}
  </div>
</div>
<div class="code-box">
  <div class="code-sample-snippet ignore">
{% highlight javascript %}
var instantsearch = require('instantsearch.js');
// TODO: include the instantsearch.js/dist/instantsearch.css file as well
{% endhighlight %}
  </div>
</div>

</div>

### Initialization

<div class="codebox-combo">

To initialize the **instantsearch.js** library you need an Algolia account with a configured & non-empty index. You'll find your Algolia credentials on the [credentials page of your dashboard](https://www.algolia.com/licensing). Use the **APPLICATION\_ID** `appId`, the **search only API\_KEY** `apiKey` and an index name `indexName` to configure the required parameters of the `instantsearch` function.

<div class="code-box">
  <div class="code-sample-snippet config">
{% highlight javascript %}
var search = instantsearch({
  appId: '$appId',
  apiKey: '$apiKey',
  indexName: '$indexName'
});
{% endhighlight %}
  </div>
  <div class="jsdoc" style="display: none">
{% highlight javascript %}
instantsearch(options);
{% endhighlight %}

{% include widget-jsdoc/instantsearch.md %}
</div>
</div>


If you don't have any index yet, learn how to push your data with the [Algolia getting started](https://www.algolia.com/getstarted).

We also expose a few options that can be used to configure the default and initial behavior of the instantsearch instance.

### Adding Widgets<commit_msg>fix(layout): missing div (did we lost that fix?)<commit_after>---
layout: documentation
title: Documentation
permalink: /documentation/
noFooter: true
---

{::options parse_block_html="true" /}

## Introduction

<div class="shameless-marketing text-center hidden-xs">
<img src="../img/logo-instantsearch.svg" height="40" alt="logo instantsearch.js"/>
<p class="lead">Build the perfect UI with Instantsearch.js,<br>an extensive library of widgets for search experience.</p>
<p class="version">Version : {{ site.version }}</p>
<div class="spacer40"></div>
<div class="row">
<div class="col-md-4 m-b">
<div class="sticker sticker-algolia">
<img src="{{site.baseurl}}/img/logo-algolia-notext.svg" width="26"/>
</div>
Built on top of <a href="https://www.algolia.com">Algolia Search API</a>
</div>
<div class="col-md-4 m-b">
<div class="sticker sticker-open-source">
<img src="{{site.baseurl}}/img/logo-open-source.svg" width="30"/>
</div>
Driven by community and available on  <a href="http://github.com/algolia/instantsearch.js">Github</a>
</div>
<div class="col-md-4 m-b">
<div class="sticker sticker-ux">
<img src="{{site.baseurl}}/img/logo-UX.svg" width="30"/>
</div>
UI/UX Best practices
</div>
</div>
</div>

**instantsearch.js** is a JavaScript library that lets you create an instant search results page using Algolia's REST API.

Everything is about adding the meaningful widgets to compose the final search results page. Widgets are the UI components that will either deal with the input of the search (like the search bar or the facets/filters over attributes) or the output (like the actual results or some meta information about the search).

Each widget is independent and their rendering is bound to the search. They follow the **instantsearch.js** lifecycle:

  - **Configuration**: each widget add new query parameters to the underlying Algolia API client.
  - **Initial rendering**: before the initial search, the widget may update the UI.
  - **Rendering**: on each search, after the results come back from Algolia, the widgets update themselves.

The library is open-source, based on [React.js](http://facebook.github.io/react/) and hosted on GitHub: [<i class="fa fa-github"></i> algolia/instantsearch.js](https://github.com/algolia/instantsearch.js). All contributions are very welcome.

### Setup

#### From a CDN
{:.no-toc}

<div class="codebox-combo">

The fastest way to get started is to use a built version of **instantsearch.js** from a CDN:

<div class="code-box">
  <div class="code-sample-snippet ignore">
{% highlight html %}
<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>
{% endhighlight %}
  </div>
</div>

</div>

This will expose the global `instantsearch` function.

#### From NPM
{:.no-toc}

<div class="codebox-combo">

If you already have a JavaScript build system, you can use **instantsearch.js** from NPM:

<div class="code-box">
  <div class="code-sample-snippet ignore">
{% highlight sh %}
npm install instantsearch.js --save
{% endhighlight %}
  </div>
</div>
<div class="code-box">
  <div class="code-sample-snippet ignore">
{% highlight javascript %}
var instantsearch = require('instantsearch.js');
// TODO: include the instantsearch.js/dist/instantsearch.css file as well
{% endhighlight %}
  </div>
</div>

</div>

### Initialization

<div class="codebox-combo">

To initialize the **instantsearch.js** library you need an Algolia account with a configured & non-empty index. You'll find your Algolia credentials on the [credentials page of your dashboard](https://www.algolia.com/licensing). Use the **APPLICATION\_ID** `appId`, the **search only API\_KEY** `apiKey` and an index name `indexName` to configure the required parameters of the `instantsearch` function.

<div class="code-box">
  <div class="code-sample-snippet config">
{% highlight javascript %}
var search = instantsearch({
  appId: '$appId',
  apiKey: '$apiKey',
  indexName: '$indexName'
});
{% endhighlight %}
  </div>
  <div class="jsdoc" style="display: none">
{% highlight javascript %}
instantsearch(options);
{% endhighlight %}

{% include widget-jsdoc/instantsearch.md %}
  </div>
</div>

</div>

If you don't have any index yet, learn how to push your data with the [Algolia getting started](https://www.algolia.com/getstarted).

We also expose a few options that can be used to configure the default and initial behavior of the instantsearch instance.

### Adding Widgets
{'fraction_non_alphanumeric': 0.14796370075254536, 'fraction_numerical': 0.0033200531208499337, 'mean_word_length': 4.830322580645161, 'pattern_counts': {'":': 0, '<': 122, '<?xml version=': 0, '>': 122, 'https://': 8, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2091362', 'n_tokens_mistral': 2894, 'n_tokens_neox': 2734, 'n_words': 947}