# Technical Documentation: algolia/instantsearch

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/algolia/instantsearch)

### Overview (`README.md`)

<p align="center">
  <a href="https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/">
    <img alt="InstantSearch.js" src=".github/banner.png">
  </a>

  <p align="center">
    InstantSearch is a JavaScript library for building performant and instant search experiences in vanilla JS, React and Vue with <a href="https://www.algolia.com/?utm_source=instantsearch.js&utm_campaign=repository">Algolia</a>.
  </p>
</p>

---

[![License][license-image]][license-url] [![Build Status][ci-svg]][ci-url]

[InstantSearch][instantsearch-docs] is a JavaScript library that lets you create an instant-search result experience using [Algolia][algolia-website]’s search API.

There are multiple wrappers for popular frameworks, such as [React InstantSearch][react-instantsearch-docs] and [Vue InstantSearch][vue-instantsearch-docs].

It is part of the InstantSearch family which is designed for different platforms:

**InstantSearch** | [InstantSearch Android][instantsearch-android-github] | [InstantSearch iOS][instantsearch-ios-github]

<details>
  <summary><strong>Table of contents</strong></summary>




- [Packages](#packages)
- [Contributing](#contributing)
- [License](#license)



</details>

## Packages

| Package | Version | Description |
| --- | --- | --- |
| [`algoliasearch-helper`](packages/algoliasearch-helper) | [](https://npmjs.org/package/algoliasearch-helper) | Helper for implementing advanced search features with Algolia |
| [`create-instantsearch-app`](packages/create-instantsearch-app) | [](https://npmjs.org/package/create-instantsearch-app) | Command-line utility to quickly bootstrap a project with InstantSearch |
| [`instantsearch.css`](packages/instantsearch.css) | [](https://npmjs.org/package/instantsearch.css) | Default CSS themes for InstantSearch |
| [`instantsearch.js`](packages/instantsearch.js) | [](https://npmjs.org/package/instantsearch.js) | InstantSearch.js |
| [`react-instantsearch`](packages/react-instantsearch) | [](https://npmjs.org/package/react-instantsearch) | React InstantSearch bundled library |
| [`react-instantsearch-core`](packages/react-instantsearch-core) | [](https://npmjs.org/package/react-instantsearch-core) | Runtime-independent React InstantSearch version |
| [`vue-instantsearch`](packages/vue-instantsearch) | [](https://npmjs.org/package/vue-instantsearch) | Vue InstantSearch |

## Contributing

We welcome all contributors, from casual to regular 💙

- **Bug report**. Is something not working as expected? [Send a bug report][contributing-bugreport].
- **Feature request**. Would you like to add something to the library? [Send a feature request][contributing-featurerequest].
- **Documentation**. Did you find a typo in the doc? [Open an issue][contributing-newissue] and we'll take care of it.
- **Development**. If you don't know where to start, you can check the open issues that are [tagged easy][contributing-label-easy], the [bugs][contributing-label-bug] or [chores][contributing-label-chore].

To start contributing to code, you need to:

1.  [Fork the project](https://help.github.com/articles/fork-a-repo/)
1.  [Clone the repository](https://help.github.com/articles/cloning-a-repository/)
1.  Install the dependencies: `yarn`
1.  [Pick a package to work on](#packages) and cd into it (e.g. `cd packages/react-instantsearch`)

Please read [our contribution process](CONTRIBUTING.md) to learn more.

## License

InstantSearch is [MIT licensed][license-url].



[ci-svg]: https://img.shields.io/circleci/project/github/algolia/instantsearch.svg?style=flat-square
[ci-url]: https://circleci.com/gh/algolia/instantsearch
[license-image]: http://img.shields.io/badge/license-MIT-green.svg?style=flat-square
[license-url]: LICENSE



[algolia-website]: https://www.algolia.com/?utm_source=instantsearch.js&utm_campaign=repository "Algolia's website"
[instantsearch-docs]: https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/?utm_source=instantsearch.js&utm_campaign=repository 'InstantSearch.js documentation'
[react-instantsearch-docs]: https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/react/?utm_source=instantsearch.js&utm_campaign=repository 'React InstantSearch documentation'
[vue-instantsearch-docs]: https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/vue/?utm_source=instantsearch.js&utm_campaign=repository 'Vue InstantSearch documentation'
[instantsearch-android-github]: https://github.com/algolia/instantsearch-android
[instantsearch-ios-github]: https://github.com/algolia/instantsearch-ios
[contributing-bugreport]: https://github.com/algolia/instantsearch/issues/new?template=BUG_REPORT.yml&labels=triage
[contributing-featurerequest]: https://github.com/algolia/instantsearch/discussions/new?category=ideas&labels=triage&title=Feature%20request%3A%20
[contributing-newissue]: https://github.com/algolia/instantsearch/issues/new?labels=triage
[contributing-label-easy]: https://github.com/algolia/instantsearch/issues?q=is%3Aopen+is%3Aissue+label%3A%22Difficulty%3A+Easy%22
[contributing-label-bug]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug%22
[contributing-label-chore]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Chore%22

---

### Overview (`packages/algoliasearch-helper/README.md`)

_Coming from V1 (or js client v2)?_ Read the [migration guide](https://github.com/algolia/algoliasearch-helper-js/wiki/Migration-guide-:-V1-to-V2) to the new version of the Helper.

_Coming from V2?_ Read the [migration guide](https://github.com/algolia/algoliasearch-helper-js/wiki/Migration-guide-:-V2-to-V3) to the new version of the Helper.

**The JavaScript helper is an advanced library we provide to our users. If you are looking to build a complete search interface, we recommend you to use [InstantSearch](https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/). If you want to build an autocomplete menu, see [Autocomplete](https://github.com/algolia/autocomplete).**

# algoliasearch-helper

This module is the companion of the [algolia/algoliasearch-client-javascript](https://github.com/algolia/algoliasearch-client-javascript). It helps you keep track of the search parameters and provides a higher level API.

[See the helper in action](https://community.algolia.com/algoliasearch-helper-js/)

[![Version][version-svg]][package-url] [![License][license-image]][license-url] [![Downloads][downloads-image]][downloads-url] [![jsDelivr Hits][jsdelivr-badge]][jsdelivr-hits]

[license-image]: http://img.shields.io/badge/license-MIT-green.svg?style=flat-square
[license-url]: LICENSE
[downloads-image]: https://img.shields.io/npm/dm/algoliasearch-helper.svg?style=flat-square
[downloads-url]: http://npm-stat.com/charts.html?package=algoliasearch-helper
[version-svg]: https://img.shields.io/npm/v/algoliasearch-helper.svg?style=flat-square
[package-url]: https://npmjs.org/package/algoliasearch-helper
[jsdelivr-badge]: https://data.jsdelivr.com/v1/package/npm/algoliasearch-helper/badge
[jsdelivr-hits]: https://www.jsdelivr.com/package/npm/algoliasearch-helper




- [Features](#features)
- [Examples](#examples)
  - [Vanilla JavaScript](#vanilla-javascript)
  - [AngularJS module](#angularjs-module)
- [Helper cheatsheet](#helper-cheatsheet)
  - [Add the helper in your project](#add-the-helper-in-your-project)
  - [Regular `<script>` tag](#regular-script-tag)
  - [With npm](#with-npm)
  - [Init the helper](#init-the-helper)
  - [Helper lifecycle](#helper-lifecycle)
  - [Objects](#objects)
  - [Search](#search)
  - [Events](#events)
  - [Query](#query)
  - [Filtering results](#filtering-results)
  - [Facet utilities](#facet-utilities)
  - [Tags](#tags)
  - [Pagination](#pagination)
  - [Index](#index)
  - [One time query](#one-time-query)
  - [Query parameters](#query-parameters)
  - [Results format](#results-format)
- [Browser support](#browser-support)



## Features

- Search parameters management
- Facets exclusions
- Pagination
- Disjunctive faceting (search on two or more values of the same facet)

## Examples

### Vanilla JavaScript

A small example that uses Browserify to manage modules.

```js
var algoliasearch = require('algoliasearch');
var algoliasearchHelper = require('algoliasearch-helper');

var client = algoliasearch('appId', 'apiKey');

var helper = algoliasearchHelper(client, 'indexName', {
  facets: ['mainCharacterFirstName', 'year'],
  disjunctiveFacets: ['director'],
});

helper.on('result', function (event) {
  console.log(event.results);
});

helper.addDisjunctiveFacetRefinement('director', 'Clint Eastwood');
helper.addDisjunctiveFacetRefinement('director', 'Sofia Coppola');

helper.addNumericRefinement('year', '=', 2003);

// Search for any movie filmed in 2003 and directed by either C. Eastwood or S. Coppola
helper.search();
```

See more examples in the [examples folder](examples/)

### AngularJS module

```js
<script src="https://cdn.jsdelivr.net/algoliasearch/3/algoliasearch.angular.js"></script>
<script src="dist/algoliasearch.helper.min.js"></script>

<script type="text/javascript">
angular.module('searchApp', ['ngSanitize', 'algoliasearch'])
.controller('searchController', ['$scope', '$sce', 'algolia', function($scope, $sce, algolia) {
  var algolia = algolia.Client('applicationId', 'apiKey');
  $scope.q = '';
  $scope.content = null;
  $scope.helper = algoliasearchHelper(algolia, 'indexName', {
    facets: ['type', 'shipping'],
    disjunctiveFacets: ['category', 'manufacturer'],
    hitsPerPage: 5,
  });
  $scope.helper.on('result', function(event) {
    $scope.$apply(function() {
      $scope.content = event.results;
    });
  });
  $scope.toggleRefine = function($event, facet, value) {
    $event.preventDefault();
    $scope.helper.toggleRefine(facet, value).search();
  };
  $scope.$watch('q', function(q) {
    $scope.helper.setQuery(q).search();
  });
  $scope.helper.search();
}]);
</script>
```

You can see the full [Angular example here](https://codepen.io/Algolia/pen/PzZobK)

## Helper cheatsheet

[There is also a complete JSDoc](https://community.algolia.com/algoliasearch-helper-js/reference.html)

### Add the helper in your project

### Regular `<script>` tag

Use our [jsDelivr](http://www.jsdelivr.com/) build:

`<script src="https://cdn.jsdelivr.net/algoliasearch.helper/2/algoliasearch.helper.min.js"></script>`

### With npm

`npm install algoliasearch-helper`

### Init the helper

```js
var helper = algoliasearchHelper(client, 'indexName' /*, parameters*/);
```

### Helper lifecycle

1. modify the parameters of the search (usually through user interactions)<br/> `helper.setQuery('iphone').addFacetRefinement('category', 'phone')`

2. trigger the search (after all the modification have been applied)<br/> `helper.search()`

3. read the results (with the event "result" handler) and update the UI with the results<br/> `helper.on('result', function(event) { updateUI(event.results); });`

4. go back to 1

### Objects

**AlgoliasearchHelper**: the helper. Keeps the state of the search, makes the queries and calls the handlers when an event happen.

**SearchParameters**: the object representing the state of the search. The current state is stored in `helperInstance.state`.

**SearchResults**: the object in which the Algolia answers are transformed into. This object is passed to the result event handler. An example of SearchResults in JSON is available at [the end of this readme](#results-format)

### Search

The search is triggered by the `search()` method.

It takes all the previous modifications to the search and uses them to create the queries to Algolia. The search parameters are immutable.

Example:

```js
var helper = algoliasearchHelper(client, indexName);

// Let's monitor the results with the console
helper.on('result', function (event) {
  console.log(event.results);
});

// Let's make an empty search
// The results are all sorted using the dashboard configuration
helper.search();

// Let's search for "landscape"
helper.setQuery('landscape').search();

// Let's add a category "photo"
// Will make a search with "photo" tag and "landscape" as the query
helper.addTag('photo').search();
```

### Events

The helper is a Node.js [EventEmitter](https://nodejs.org/api/events.html#events_class_events_eventemitter) instance.

`result`: get notified when new results are received. The handler function will receive two objects (`SearchResults` and `SearchParameters`).

`error`: get notified when errors are received from the API.

`change`: get notified when a property has changed in the helper

`search` : get notified when a request is sent to Algolia

#### Listen to the `result` event

```js
helper.on('result', updateTheResults);
```

#### Listen to a `result` event once

```js
helper.once('result', updateTheResults);
```

#### Remove a `result` listener

```js
helper.removeListener('result', updateTheResults);
```

#### Remove all `result` listeners

```js
helper.removeAllListeners('result');
```

All the methods from Node.js [EventEmitter](https://nodejs.org/api/events.html#events_class_events_eventemitter) class are available.

### Query

#### Do a search with the query "fruit"

```javscript
helper.setQuery('fruit').search();
```

### Filtering results

Facets are filters to retrieve a subset of an index having a specific value for a given attribute. First you need to define which attribute will be used as a facet in the dashboard: [https://www.algolia.com/explorer#?tab=display](https://www.algolia.com/explorer#?tab=display)

#### Regular (conjunctive) facets

Refinements are ANDed by default (Conjunctive selection).

##### Facet definition

```js
var helper = algoliasearchHelper(client, indexName, {
  facets: ['ANDFacet'],
});
```

##### Add a facet filter

```js
helper.addFacetRefinement('ANDFacet', 'valueOfANDFacet').search();
```

##### Remove a facet filter

```js
helper.removeFacetRefinement('ANDFacet', 'valueOfANDFacet').search();
```

#### Disjunctive facets

Refinements are ORed by default (Disjunctive selection).

##### Facet definition

```js
var helper = algoliasearchHelper(client, indexName, {
  disjunctiveFacets: ['ORFacet'],
});
```

##### Add a facet filter

```js
helper.addDisjunctiveFacetRefinement('ORFacet', 'valueOfORFacet').search();
```

##### Remove a facet filter

```js
helper.removeDisjunctiveFacetRefinement('ORFacet', 'valueOfORFacet').search();
```

#### Negative facets

Filter so that we do NOT get a given facet

##### Facet definition (same as "AND" facet)

```js
var helper = algoliasearchHelper(client, indexName, {
  facets: ['ANDFacet'],
}).search();
```

##### Exclude a value for a facet

```js
helper.addFacetExclusion('ANDFacet', 'valueOfANDFacetToExclude');
```

##### Remove an exclude from the list of excluded values

```js
helper.removeFacetExclusion('ANDFacet', 'valueOfANDFacetToExclude');
```

#### Numeric facets

Filter over numeric attributes with math operations like `=`, `>`, `<`, `>=`, `<=`. Can be used for numbers and dates (if converted to timestamp)

##### Facet definition

```js
var helper = algoliasearchHelper(client, indexName, {
  disjunctiveFacets: ['numericAttribute'],
});
```

##### Add numeric refinements

```js
helper.addNumericRefinement('numericAttribute', '=', '3').search();
// filter to only the results that match numericAttribute=3
helper.addNumericRefinement('numericAttribute', '=', '4').search();
// filter to only the results that match numericAttribute=3 AND numericAttribute=4

// On another numeric with no previous filter
helper
  .addNumericRefinement('numericAttribute2', '=', ['42', '56', '37'])
  .search();
// filter to only the results that match numericAttribute2=42 OR numericAttribute2=56 OR numericAttribute2=37
```

##### Remove a numeric refinement

```js
helper.removeNumericRefinement('numericAttribute', '=', '3').search();
```

##### Batch numeric filter removal

```js
// for the single operator = on numericAttribute
helper.removeNumericRefinement('numericAttribute', '=').search();
// for all the refinements on numericAttribute
helper.removeNumericRefinement('numericAttribute').search();
```

#### Hierarchical facets

Hierarchical facets are useful to build such navigation menus:

```txt
| products
  > fruits
    > citrus
    | strawberries
    | peaches
    | apples
```

Here, we refined the search this way:

- click on fruits
- click on citrus

##### Usage

To build such menu, you need to use hierarchical faceting:

```javascript
var helper = algoliasearchHelper(client, indexName, {
  hierarchicalFacets: [
    {
      name: 'products',
      attributes: ['categories.lvl0', 'categories.lvl1'],
    },
  ],
});
```

**Requirements:** All the specified `attributes` must be defined in your Algolia settings as attributes for faceting.

Given your objects looks like this:

```json
{
  "objectID": "123",
  "name": "orange",
  "categories": {
    "lvl0": "fruits",
    "lvl1": "fruits > citrus"
  }
}
```

And you refine `products`:

```js
helper.toggleFacetRefinement('products', 'fruits > citrus');
```

You will get a hierarchical presentation of your facet values: a navigation menu of your facet values.

```js
helper.on('result', function (event) {
  console.log(event.results.hierarchicalFacets[0]);
  // {
  //   'name': 'products',
  //   'count': null,
  //   'isRefined': true,
  //   'path': null,
  //   'data': [{
  //     'name': 'fruits',
  //     'path': 'fruits',
  //     'count': 1,
  //     'isRefined': true,
  //     'data': [{
  //       'name': 'citrus',
  //       'path': 'fruits > citrus',
  //       'count': 1,
  //       'isRefined': true,
  //       'data': null
  //     }]
  //   }]
  // }
});
```

To ease navigation, we always:

- provide the root level categories
- provide the current refinement sub categories (`fruits > citrus > *`: n + 1)
- provide the parent refinement (`fruits > citrus` => `fruits`: n -1) categories
- refine the search using the current hierarchical refinement

##### Multiple values per level

Your records can also share multiple categories between one another by using arrays inside your object:

```json
{
  "objectID": "123",
  "name": "orange",
  "categories": {
    "lvl0": ["fruits", "color"],
    "lvl1": ["fruits > citrus", "color > orange"]
  }
},
{
  "objectID": "456",
  "name": "grapefruit",
  "categories": {
    "lvl0": ["fruits", "color", "new"],
    "lvl1": ["fruits > citrus", "color > yellow", "new > citrus"]
  }
}
```

##### Specifying another separator

```js
var helper = algoliasearchHelper(client, indexName, {
  hierarchicalFacets: [
    {
      name: 'products',
      attributes: ['categories.lvl0', 'categories.lvl1'],
      separator: '|',
    },
  ],
});

helper.toggleFacetRefinement('products', 'fruits|citrus');
```

Would mean that your objects look like so:

```json
{
  "objectID": "123",
  "name": "orange",
  "categories": {
    "lvl0": "fruits",
    "lvl1": "fruits|citrus"
  }
}
```

##### Specifying a different sort order for values

The default sort for the hierarchical facet view is: `isRefined:desc (first show refined), name:asc (then sort by name)`.

You can specify a different sort order by using:

```js
var helper = algoliasearchHelper(client, indexName, {
  hierarchicalFacets: [
    {
      name: 'products',
      attributes: ['categories.lvl0', 'categories.lvl1'],
      sortBy: ['count:desc', 'name:asc'], // first show the most common values, then sort by name
    },
  ],
});
```

The available sort tokens are:

- count
- isRefined
- name
- path

##### Restrict results and hierarchical values to non-root level

Let's say you have a lot of levels:

```
- fruits
  - yellow
    - citrus
      - spicy
```

But you only want to get the values starting at "citrus", you can use `rootPath`

You can specify an root path to filter the hierarchical values

```
var helper = algoliasearchHelper(client, indexName, {
  hierarchicalFacets: [{
    name: 'products',
    attributes: ['categories.lvl0', 'categories.lvl1', 'categories.lvl2', 'categories.lvl3'],
    rootPath: 'fruits > yellow > citrus'
  }]
});
```

Having a rootPath will refine the results on it **automatically**.

##### Hide parent level of current parent level

By default the hierarchical facet is going to return the child and parent facet values of the current refinement.

If you do not want to get the parent facet values you can set showParentLevel to false

```js
var helper = algoliasearchHelper(client, indexName, {
  hierarchicalFacets: [
    {
      name: 'products',
      attributes: ['categories.lvl0', 'categories.lvl1'],
      showParentLevel: false,
    },
  ],
});
```

##### Asking for the current breadcrumb

```js
var helper = algoliasearchHelper(client, indexName, {
  hierarchicalFacets: [
    {
      name: 'products',
      attributes: ['categories.lvl0', 'categories.lvl1'],
      separator: '|',
    },
  ],
});

helper.toggleFacetRefinement('products', 'fruits|citrus');
var breadcrumb = helper.getHierarchicalFacetBreadcrumb('products');

console.log(breadcrumb);
// ['fruits', 'citrus']

console.log(breadcrumb.join(' | '));
// 'fruits | citrus'
```

#### Clearing filters

##### Clear all the refinements for all the refined attributes

```js
helper.clearRefinements().search();
```

##### Clear all the refinements for a specific attribute

```js
helper.clearRefinements('ANDFacet').search();
```

##### [ADVANCED] Clear only the exclusions on the "ANDFacet" attribute

```js
helper
  .clearRefinements(function (value, attribute, type) {
    return type === 'exclude' && attribute === 'ANDFacet';
  })
  .search();
```

### Facet utilities

#### Get the values of a facet with the default sort

```js
helper.on('result', function (event) {
  // Get the facet values for the attribute age
  event.results.getFacetValues('age');
  // It will be ordered :
  //  - refined facets first
  //  - then ordered by number of occurence (bigger count -> higher in the list)
  //  - then ordered by name (alphabetically)
});
```

#### Get the values of a facet with a custom sort

```js
helper.on('result', function (event) {
  // Get the facet values for the attribute age
  event.results.getFacetValues('age', { sortBy: ['count:asc'] });
  // It will be ordered by number of occurence (lower number => higher position)
  // Elements that can be sorted : count, name, isRefined
  // Type of sort : 'asc' for ascending order, 'desc' for descending order
});
```

#### Get the facet stats

_This only apply on numeric based facets/attributes._

```js
helper.on('result', function (event) {
  // Get the facet values for the attribute age
  event.results.getFacetStats('age');
});
```

### Tags

Tags are an easy way to do filtering. They are based on a special attribute in the records named `_tags`, which can be a single string value or an array of strings.

#### Add a tag filter for the value "landscape"

```js
helper.addTag('landscape').search();
```

#### Remove a tag filter for the value "landscape"

```js
helper.removeTag('landscape').search();
```

#### Clear all the tags filters

```js
helper.clearTags().search();
```

### Pagination

#### Get the current page

```js
helper.getPage();
```

#### Change page

```js
helper.setPage(3).search();
```

#### Automatic reset to page 0

During a search, changing the parameters will update the result set, which can then change the number of pages in the result set. Therefore, the behavior has been standardized so that any operation that may change the number of page will reset the pagination to page 0.

This may lead to some unexpected behavior. For example:

```js
helper.setPage(4);
helper.getPage(); // 4
helper.setQuery('foo');
helper.getPage(); // 0
```

Non exhaustive list of operations that trigger a reset:

- refinements (conjunctive, exclude, disjunctive, hierarchical, numeric)
- tags
- index (setIndex)
- setQuery
- setHitsPerPage
- setTypoTolerance

### Index

Index can be changed. The common use case is when you have several slaves with different sort order (sort by relevance, price or any other attribute).

#### Change the current index

```js
helper.setIndex('index_orderByPrice').search();
```

#### Get the current index

```js
var currentIndex = helper.getIndex();
```

### One time query

Sometime it's convenient to reuse the current search parameters with small changes without changing the state stored in the helper. That's why there is a function called `searchOnce`. This method does not trigger `change` or `error` events.

In the following, we are using `searchOnce` to fetch only a single element using all the other parameters already set in the search parameters.

#### Using searchOnce with a callback

```js
var state = helper.searchOnce(
  { hitsPerPage: 1 },
  function (error, content, state) {
    // if an error occured it will be passed in error, otherwise its value is null
    // content contains the results formatted as a SearchResults
    // state is the instance of SearchParameters used for this search
  }
);
```

#### Using searchOnce with a promise

```js
var state1 = helper.searchOnce({ hitsPerPage: 1 }).then(function (res) {
  // res contains
  // {
  //   content : SearchResults
  //   state : SearchParameters (the one used for this specific search)
  // }
});
```

### Query parameters

There are lots of other parameters you can set.

#### Set a parameter at the initialization of the helper

```js
var helper = algoliasearchHelper(client, indexName, {
  hitsPerPage: 50,
});
```

#### Set a parameter later

```js
helper.setQueryParameter('hitsPerPage', 20).search();
```

#### List of parameters that can be set

<table cellspacing="0" cellpadding="0" class="params">
  <tbody>
    <tr>
      <td valign="top" class="td1">
        <p class="p1"><span class="s1"><b>Name</b></span></p>
      </td>
      <td valign="top" class="td2">
        <p class="p1"><span class="s1"><b>Type</b></span></p>
      </td>
      <td valign="top" class="td3">
        <p class="p1"><span class="s1"><b>Description</b></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">advancedSyntax</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Enable the advanced syntax.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/advancedSyntax/">advancedSyntax on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">allowTyposOnNumericTokens</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Should the engine allow typos on numerics.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/allowTyposOnNumericTokens/">allowTyposOnNumericTokens on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">analytics</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Enable the analytics</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/analytics/">analytics on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">analyticsTags</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Tag of the query in the analytics.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/analyticsTags/">analyticsTags on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">aroundLatLng</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Center of the geo search.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/aroundLatLng/">aroundLatLng on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">aroundLatLngViaIP</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Center of the search, retrieve from the user IP.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/aroundLatLngViaIP/">aroundLatLngViaIP on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">aroundPrecision</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Precision of the geo search.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/aroundPrecision/">aroundPrecision on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">aroundRadius</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Radius of the geo search.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/aroundRadius/">aroundRadius on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">minimumAroundRadius</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Minimum radius of the geo search.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/minimumAroundRadius/">minimumAroundRadius on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">attributesToHighlight</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">List of attributes to highlight</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/attributesToHighlight/">attributesToHighlight on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">attributesToRetrieve</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">List of attributes to retrieve</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/attributesToRetrieve/">attributesToRetrieve on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">attributesToSnippet</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">List of attributes to snippet</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/attributesToSnippet/">attributesToSnippet on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">disjunctiveFacets</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">Array.&lt;string&gt;</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p1"><span class="s1">All the declared disjunctive facets</span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">distinct</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean|number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Remove duplicates based on the index setting attributeForDistinct</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/distinct/">distinct on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">facets</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">Array.&lt;string&gt;</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p1"><span class="s1">All the facets that will be requested to the server</span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">filters</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p1"><span class="s1">Add filters to the query (similar to WHERE clauses)</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/filters/">filters on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">getRankingInfo</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">integer</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Enable the ranking informations in the response</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/getRankingInfo/">getRankingInfo on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">hitsPerPage</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Number of hits to be returned by the search API</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/hitsPerPage/">hitsPerPage on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">ignorePlurals</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Should the plurals be ignored</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/ignorePlurals/">ignorePlurals on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">insideBoundingBox</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Geo search inside a box.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/insideBoundingBox/">insideBoundingBox on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">insidePolygon</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Geo search inside a polygon.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/insidePolygon/">insidePolygon on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">maxValuesPerFacet</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Number of values for each facetted attribute</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/maxValuesPerFacet/">maxValuesPerFacet on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">minWordSizefor1Typo</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Number of characters to wait before doing one character replacement.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/minWordSizefor1Typo/">minWordSizefor1Typo on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">minWordSizefor2Typos</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Number of characters to wait before doing a second character replacement.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/minWordSizefor2Typos/">minWordSizefor2Typos on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">optionalWords</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Add some optional words to those defined in the dashboard</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/optionalWords/">optionalWords on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">page</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">number</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">The current page number</span></p>
        <p class="p5"><span class="s1"><a href="algolia.com/doc/api-reference/api-parameters/page/">page on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">query</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Query string of the instant search. The empty string is a valid query.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/query/">query on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">queryType</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">How the query should be treated by the search engine. Possible values: prefixAll, prefixLast, prefixNone</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/queryType/">queryType on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">removeWordsIfNoResults</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Possible values are "lastWords" "firstWords" "allOptional" "none" (default)</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/removeWordsIfNoResults/">removeWordsIfNoResults on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">replaceSynonymsInHighlight</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Should the engine replace the synonyms in the highlighted results.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/replaceSynonymsInHighlight/">replaceSynonymsInHighlight on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">restrictSearchableAttributes</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Restrict which attribute is searched.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/restrictSearchableAttributes/">restrictSearchableAttributes on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">synonyms</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">boolean</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Enable the synonyms</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/synonyms/">synonyms on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">tagFilters</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">Contains the tag filters in the raw format of the Algolia API. Setting this parameter is not compatible with the of the add/remove/toggle methods of the tag api.</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/tagFilters/">tagFilters on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
    <tr>
      <td valign="top" class="td4">
        <p class="p2"><span class="s2">typoTolerance</span></p>
      </td>
      <td valign="top" class="td5">
        <p class="p3"><span class="s1">string</span></p>
      </td>
      <td valign="top" class="td6">
        <p class="p4"><span class="s1">How the typo tolerance behave in the search engine. Possible values: true, false, min, strict</span></p>
        <p class="p5"><span class="s1"><a href="https://www.algolia.com/doc/api-reference/api-parameters/typoTolerance/">typoTolerance on Algolia.com<span class="s3"></span></a></span></p>
      </td>
    </tr>
  </tbody>
</table>

### Results format

Here is an example of a result object you get with the `result` event.

```
/* Detailed source-code truncated for AI context efficiency. */
```

## Browser support

This project works on any [ES5](https://en.wikipedia.org/wiki/ECMAScript#5th_Edition) browser, basically >= IE9+.

---

### Overview (`packages/create-instantsearch-app/README.md`)

# Create InstantSearch App

> ⚡️ Build InstantSearch apps at the speed of thought.

[![Version][version-svg]][package-url] [![License][license-image]][license-url] [![Build Status][ci-svg]][ci-url]

`create-instantsearch-app` is a command line utility that helps you quick start your InstantSearch app using any [Algolia][algolia-website] InstantSearch flavor ([InstantSearch.js][instantsearchjs-github], [React InstantSearch][react-instantsearch-github], [Vue InstantSearch][vue-instantsearch-github], [InstantSearch iOS][instantsearch-ios-github] and [InstantSearch Android][instantsearch-android-github]).

<p align="center">
  <img src="preview.png" width="800" alt="Preview">
</p>

<details>
  <summary><strong>Contents</strong></summary>




- [Get started](#get-started)
- [Usage](#usage)
- [API](#api)
- [Tutorials](#tutorials)
- [Previews](#previews)
- [Contributing](#contributing)
- [License](#license)



</details>

## Get started

> The tool requires Node ≥ 8.

```
npx create-instantsearch-app my-app
cd my-app
npm start
```

> [`npx`](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) is a tool introduced in `npm@5.2.0` that makes it possible to run CLI tools hosted on the npm registry.

---

Alternatively, you can use [Yarn](https://yarnpkg.com):

```
yarn create instantsearch-app my-app
cd my-app
yarn start
```

> **Important** Selecting 'Y' when being prompted to ‘Enable user events’ activates the [`insights`](https://www.algolia.com/doc/api-reference/widgets/instantsearch/js/#widget-param-insights) option for compatible templates, allowing Algolia to process your user Events. Events can unlock powerful features, enhancing your application's effectiveness and we encourage you to consider enabling this valuable functionality. Please review our [API reference](https://www.algolia.com/doc/api-reference/widgets/instantsearch/js/#widget-param-insights) for more details about Events collection and settings.

## Usage

This package comes with the module `createInstantSearchApp(path, options?)` and the command-line tool `create-instantsearch-app`.

```
$ create-instantsearch-app --help

  Usage: create-instantsearch-app <project-directory> [options]

  Options:

    -v, --version                                      output the version number
    --name <name>                                      The name of the application
    --app-id <appId>                                   The application ID
    --api-key <apiKey>                                 The Algolia search API key
    --index-name <indexName>                           The main index of your search
    --attributes-to-display <attributesToDisplay>      The attributes of your index to display
    --image-attribute <imageAttribute>                 The attribute of your index to use for image display
    --attributes-for-faceting <attributesForFaceting>  The attributes for faceting
    --template <template>                              The InstantSearch template to use
    --library-version <libraryVersion>                 The version of the library
    --config <config>                                  The configuration file to get the options from
    --no-installation                                  Ignore dependency installation
    --no-interactive                                   Do not ask any interactive questions
    -h, --help                                         output usage information
```

#### `--template`

Supported templates are:

- [`InstantSearch.js`][instantsearchjs-github]
- [`React InstantSearch`][react-instantsearch-github]
- [`React InstantSearch Native`][react-instantsearch-github]
- [`Vue InstantSearch`][vue-instantsearch-github]
- [`InstantSearch iOS`][instantsearch-ios-github]
- [`InstantSearch Android`][instantsearch-android-github]

```
create-instantsearch-app my-app --template "React InstantSearch"
```

You can also [create your own template](docs/custom-templates.md) and specify its path.

#### `--config`

The `config` flag is handy to automate app generations.

<h6 align="center">config.json</h6>

```json
{
  "name": "my-app",
  "template": "InstantSearch.js",
  "libraryVersion": "2.8.0",
  "appId": "MY_APP_ID",
  "apiKey": "MY_API_KEY",
  "indexName": "MY_INDEX_NAME",
  "searchPlaceholder": "Search",
  "attributesToDisplay": ["name", "description"],
  "imageAttribute": "image",
  "attributesForFaceting": ["brand", "location"],
  "enableInsights": true
}
```

Create the app based on this configuration:

```
create-instantsearch-app my-app --config config.json
```

## API

`create-instantsearch-app` is based on the module `createInstantSearchApp(path, options?)`. The same [camel cased](https://en.wikipedia.org/wiki/Camel_case) options as the CLI are available.

```javascript
const createInstantSearchApp = require('create-instantsearch-app');

const app = createInstantSearchApp('~/lab/my-app', {
  template: 'InstantSearch.js',
  libraryVersion: '2.0.0',
  attributesToDisplay: ['name', 'description'],
  imageAttribute: 'image',
  attributesForFaceting: ['keywords'],
  enableInsights: true,
});

app.create().then(() => console.log('App generated!'));
```

## Tutorials

- [Creating a custom template](docs/custom-templates.md)
- [Deploying an InstantSearch App](docs/deploy.md)

## Previews

You can use the web templates on CodeSandbox:

- [InstantSearch.js](https://codesandbox.io/s/github/algolia/instantsearch/tree/templates/instantsearch.js)
- [React InstantSearch](https://codesandbox.io/s/github/algolia/instantsearch/tree/templates/react-instantsearch)
- [Vue InstantSearch](https://codesandbox.io/s/github/algolia/instantsearch/tree/templates/vue-instantsearch)
- [Autocomplete.js](https://codesandbox.io/s/github/algolia/instantsearch/tree/templates/autocomplete.js)
- [JavaScript Client](https://codesandbox.io/s/github/algolia/instantsearch/tree/templates/javascript-client)
- [JavaScript Helper](https://codesandbox.io/s/github/algolia/instantsearch/tree/templates/javascript-helper)

## Contributing

We welcome all contributors, from casual to regular 💙

- **Bug report**. Is something not working as expected? [Send a bug report][contributing-bugreport].
- **Feature request**. Would you like to add something to the library? [Send a feature request][contributing-featurerequest].
- **Development**. If you don't know where to start, you can check the open issues that are [tagged easy][contributing-label-easy], the [bugs][contributing-label-bug] or [chores][contributing-label-chore].

To start contributing to the code, you need to:

1.  [Fork the project](https://help.github.com/articles/fork-a-repo/)
1.  [Clone the repository](https://help.github.com/articles/cloning-a-repository/)
1.  Install the dependencies: `yarn`

Please read [our contribution process](https://github.com/algolia/instantsearch/blob/master/CONTRIBUTING.md) to learn more.

## License

Create InstantSearch App is [MIT licensed](LICENSE).



[version-svg]: https://img.shields.io/npm/v/create-instantsearch-app.svg?style=flat-square
[package-url]: https://npmjs.org/package/create-instantsearch-app
[ci-svg]: https://img.shields.io/circleci/project/github/algolia/create-instantsearch-app.svg?style=flat-square
[ci-url]: https://circleci.com/gh/algolia/instantsearch
[license-image]: https://img.shields.io/badge/license-MIT-green.svg?style=flat-square
[license-url]: LICENSE



[algolia-website]: https://www.algolia.com/?utm_medium=social-owned&utm_source=GitHub&utm_campaign=create-instantsearch-app%20repository
[instantsearchjs-github]: https://github.com/algolia/instantsearch/tree/master/packages/instantsearch.js
[react-instantsearch-github]: https://github.com/algolia/instantsearch/tree/master/packages/react-instantsearch
[vue-instantsearch-github]: https://github.com/algolia/instantsearch/tree/master/packages/vue-instantsearch
[instantsearch-ios-github]: https://github.com/algolia/instantsearch-ios
[instantsearch-android-github]: https://github.com/algolia/instantsearch-android
[contributing-bugreport]: https://github.com/algolia/instantsearch/issues/new?template=BUG_REPORT.yml&labels=triage,Library%3A%20Create+InstantSearch+App
[contributing-featurerequest]: https://github.com/algolia/instantsearch/discussions/new?category=ideas&labels=triage,Library%3A%20Create+InstantSearch+App&title=Feature%20request%3A%20
[contributing-label-easy]: https://github.com/algolia/instantsearch/issues?q=is%3Aopen+is%3Aissue+label%3A%22Difficulty%3A+Easy%22+label%3A%22Library%3A%20Create+InstantSearch+App%22
[contributing-label-bug]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug%22+label%3A%22Library%3A%20Create+InstantSearch+App%22
[contributing-label-chore]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Chore%22+label%3A%22Library%3A%20Create+InstantSearch+App%22

---

### Overview (`packages/instantsearch-codemods/README.md`)

- [Codemods](#codemods)
  - [`rish-to-ris`](#rish-to-ris)
  - [`ris-v6-to-v7`](#ris-v6-to-v7)
  - [`addWidget-to-addWidgets`](#addwidget-to-addwidgets)
  - [Notes](#notes)



## Codemods

These codemods (code transformers) can be ran with [jscodeshift](https://github.com/facebook/jscodeshift).

### `rish-to-ris`

This will replace all imports from `react-instantsearch-hooks` to their `react-instantsearch` equivalent.

```
npx @codeshift/cli --packages 'instantsearch-codemods#rish-to-ris' <path>
```

### `ris-v6-to-v7`

This will:

- Replace `react-instantsearch-dom` imports to `react-instantsearch`
- Replace prop names to their new equivalent
- Replace `translations` keys to their new equivalent if they are defined inline, otherwise it will add a TODO comment
- Add some TODO comments to help you migrate

```
npx @codeshift/cli --packages 'instantsearch-codemods#ris-v6-to-v7' <path>
```

### `addWidget-to-addWidgets`

This will replace all `addWidget` calls to `addWidgets` and `removeWidget` calls to `removeWidgets`.

```
npx @codeshift/cli --packages 'instantsearch-codemods#addWidget-to-addWidgets' <path>
```

### Notes

If you are using a formatter or a linter, make sure to run its autofixing after this transformation, since code can be formatted differently after it has been transformed. In our repository, that would be:

```
yarn format
```

---

### Overview (`packages/instantsearch-ui-components/README.md`)

- [instantsearch-ui-components](#instantsearch-ui-components)
  - [Contributing](#contributing)
  - [License](#license)



# instantsearch-ui-components

InstantSearch UI Components is an open-source UI library used by InstantSearch to build UI for search and discovery interfaces. It exports UI components that are compatible with InstantSearch.js, React InstantSearch, and Vue InstantSearch.

> Note: `instantsearch-ui-components` exists for internal usage and isn't designed for public consumption.

## Contributing

We welcome all contributors, from casual to regular 💙

- **Bug report**. Is something not working as expected? [Send a bug report][contributing-bugreport].
- **Feature request**. Would you like to add something to the library? [Send a feature request][contributing-featurerequest].
- **Documentation**. Did you find a typo in the doc? [Open an issue][contributing-newissue] and we'll take care of it.
- **Development**. If you don't know where to start, you can check the open issues that are [tagged easy][contributing-label-easy], the [bugs][contributing-label-bug] or [chores][contributing-label-chore].

To start contributing to code, you need to:

1.  [Fork the project](https://help.github.com/articles/fork-a-repo/)
1.  [Clone the repository](https://help.github.com/articles/cloning-a-repository/)
1.  Install the dependencies: `yarn`

Please read [our contribution process](https://github.com/algolia/instantsearch/blob/master/CONTRIBUTING.md) to learn more.

## License

InstantSearch UI Components is [MIT licensed](../../LICENSE).



[contributing-bugreport]: https://github.com/algolia/instantsearch/issues/new?template=BUG_REPORT.yml&labels=triage,Library%3A%20React+InstantSearch
[contributing-featurerequest]: https://github.com/algolia/instantsearch/discussions/new?category=ideas&labels=triage,Library%3A%20React+InstantSearch&title=Feature%20request%3A%20
[contributing-newissue]: https://github.com/algolia/instantsearch/issues/new?labels=triage,Library%3A%20React+InstantSearch
[contributing-label-easy]: https://github.com/algolia/instantsearch/issues?q=is%3Aopen+is%3Aissue+label%3A%22Difficulty%3A+Easy%22+label%3A%22Library%3A%20React+InstantSearch%22
[contributing-label-bug]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug%22+label%3A%22Library%3A%20React+InstantSearch%22
[contributing-label-chore]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Chore%22+label%3A%22Library%3A%20React+InstantSearch%22

---

### Overview (`packages/instantsearch.css/README.md`)

- [Getting started](#getting-started)
- [Installation](#installation)
- [Available themes](#available-themes)
- [Browser support](#browser-support)
- [Implemented versions](#implemented-versions)
- [Contributing](#contributing)
- [License](#license)



<p align="center">
  <p align="center">
    InstantSearch.css is a CSS library to style InstantSearch-powered search experiences.
  </p>
</p>

---

[![Version][version-svg]][package-url] [![License][license-image]][license-url] [![Build Status][ci-svg]][ci-url] [![Website][website-svg]][website-url]

## Getting started

Using InstantSearch.css is as simple as adding this CSS code to your existing InstantSearch app:

```js
// Include only the reset
import 'instantsearch.css/themes/reset.css';

// Or include the full Satellite theme
import 'instantsearch.css/themes/satellite.css';
```

To learn more about the library, follow the guide on how to style your InstantSearch widgets:

- [InstantSearch.js](https://www.algolia.com/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js/#style-your-widgets)
- [React InstantSearch](https://www.algolia.com/doc/guides/building-search-ui/widgets/customize-an-existing-widget/react/#style-your-widgets)
- [Vue InstantSearch](https://www.algolia.com/doc/guides/building-search-ui/widgets/customize-an-existing-widget/vue/#style-your-widgets)

## Installation

```sh
npm install instantsearch.css
# or
yarn add instantsearch.css
```

## Available themes

InstantSearch.css exposes two themes:

- [Algolia](src/themes/algolia.scss)
- [Satellite](src/themes/satellite.scss)

If you don't need a theme, you can still use the [reset styles](src/themes/reset.scss) to start from a clean slate.

**The reset styles are included in all the provided themes.** You don't need to import them if you use a theme.

## Browser support

We support the **last two versions of major browsers** (Chrome, Edge, Firefox, Safari).

## Implemented versions

InstantSearch.css is a living standard. This table tracks down the version implemented in each InstantSearch flavor.

| Project             | Version |
| ------------------- | ------- |
| InstantSearch.js    | 7       |
| React InstantSearch | 7       |
| Vue InstantSearch   | 7       |

## Contributing

We welcome all contributors, from casual to regular 💙

- **Bug report**. Is something not working as expected? [Send a bug report][contributing-bugreport].
- **Feature request**. Would you like to add something to the library? [Send a feature request][contributing-featurerequest].
- **Documentation**. Did you find a typo in the doc? [Open an issue][contributing-newissue] and we'll take care of it.
- **Development**. If you don't know where to start, you can check the open issues that are [tagged easy][contributing-label-easy], the [bugs][contributing-label-bug] or [chores][contributing-label-chore].

To start contributing to code, you need to:

1.  [Fork the project](https://help.github.com/articles/fork-a-repo/)
1.  [Clone the repository](https://help.github.com/articles/cloning-a-repository/)
1.  Install the dependencies: `yarn`

Please read [our contribution process](https://github.com/algolia/instantsearch/blob/master/CONTRIBUTING.md) to learn more.

## License

InstantSearch.css is [MIT licensed][license-url].



[version-svg]: https://img.shields.io/npm/v/instantsearch.css.svg?style=flat-square
[package-url]: https://npmjs.org/package/instantsearch.css
[ci-svg]: https://img.shields.io/circleci/project/github/algolia/instantsearch.svg?style=flat-square
[ci-url]: https://circleci.com/gh/algolia/instantsearch
[license-image]: http://img.shields.io/badge/license-MIT-green.svg?style=flat-square
[website-svg]: https://img.shields.io/badge/website-instantsearchjs.netlify.app/specs-yellow?style=flat-square
[website-url]: https://instantsearchjs.netlify.app/specs/
[license-url]: LICENSE



[contributing-bugreport]: https://github.com/algolia/instantsearch/issues/new?template=BUG_REPORT.yml&labels=triage,Library%3A%20InstantSearch.css
[contributing-featurerequest]: https://github.com/algolia/instantsearch/discussions/new?category=ideas&labels=triage,Library%3A%20InstantSearch.css&title=Feature%20request%3A%20
[contributing-newissue]: https://github.com/algolia/instantsearch/issues/new?labels=triage,Library%3A%20InstantSearch.css
[contributing-label-easy]: https://github.com/algolia/instantsearch/issues?q=is%3Aopen+is%3Aissue+label%3A%22Difficulty%3A+Easy%22+label%3A%22Library%3A%20InstantSearch.css%22
[contributing-label-bug]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug%22+label%3A%22Library%3A%20InstantSearch.css%22
[contributing-label-chore]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Chore%22+label%3A%22Library%3A%20InstantSearch.css%22

---

### Overview (`packages/instantsearch.js/README.md`)

<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>

---

InstantSearch.js is a vanilla JavaScript library that lets you create an instant-search result experience using [Algolia][algolia-website]’s search API. It is part of the InstantSearch family:

**InstantSearch.js** | [React InstantSearch][instantsearch-github] | [Vue InstantSearch][instantsearch-github] | [React InstantSearch Native][instantsearch-github] | [InstantSearch Android][instantsearch-android-github] | [InstantSearch iOS][instantsearch-ios-github]

<details>
  <summary><strong>Table of contents</strong></summary>




- [Why](#why)
- [Getting started](#getting-started)
- [Installation](#installation)
  - [TypeScript users](#typescript-users)
- [Documentation](#documentation)
- [Demos](#demos)
- [Playground](#playground)
- [Browser support](#browser-support)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)



</details>

## Why

You should be using InstantSearch if you want to:

- Design search experiences with best practices
- Customize your components at will
- Remain independent from external frameworks

## Getting started

Using InstantSearch.js is as simple as adding this JavaScript code to your page:

```javascript
// 1. Instantiate the search
const search = instantsearch({
  indexName: 'instant_search',
  searchClient: algoliasearch('latency', '6be0576ff61c053d5f9a3225e2a90f76'),
});

search.addWidgets([
  // 2. Create an interactive search box
  instantsearch.widgets.searchBox({
    container: '#searchbox',
    placeholder: 'Search for products',
  }),

  // 3. Plug the search results into the product container
  instantsearch.widgets.hits({
    container: '#products',
    templates: {
      item: (hit, { html, components }) => html`
        <h3>${components.Highlight({ attribute: 'name', hit })}</h3>
        <p>${components.Snippet({ attribute: 'description', hit })}</p>
      `,
    },
  }),

  // 4. Make the brands refinable
  instantsearch.widgets.refinementList({
    container: '#brand',
    attribute: 'brand',
  }),
]);

// 5. Start the search!
search.start();
```

<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>

To learn more about the library, follow the [getting started](https://www.algolia.com/doc/guides/building-search-ui/getting-started/js/) guide or check how to [add it to your own project](https://www.algolia.com/doc/guides/building-search-ui/installation/js/).

## Installation

```sh
npm install instantsearch.js algoliasearch
# or
yarn add instantsearch.js algoliasearch
```

### TypeScript users

To use InstantSearch.js in a TypeScript environment, depending on your [`algoliasearch`](https://github.com/algolia/algoliasearch-client-javascript) version, you need to import different types.

> You still need to import these types even if you don't use InstantSearch.js with [`algoliasearch`](https://github.com/algolia/algoliasearch-client-javascript).

#### `algoliasearch` v4.x

This version uses types provided by both `algoliasearch` and `@algolia/client-search`.

```bash
yarn add algoliasearch@4 @algolia/client-search
```

#### `algoliasearch` v3.x

```bash
yarn add @types/algoliasearch@3
```

> v3.x is deprecated and will soon no longer be supported.

## Documentation

The documentation is available on the [Algolia website](https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js/).

## Demos

| E-commerce | Media | Travel |
| --- | --- | --- |
| <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> | <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> | <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> |

See more demos [on the website](https://www.algolia.com/doc/guides/building-search-ui/resources/demos/js/).

## Playground

You can get to know InstantSearch.js on [this playground](https://codesandbox.io/s/github/algolia/create-instantsearch-app/tree/templates/instantsearch.js).

Start by [adding widgets](https://www.algolia.com/doc/guides/building-search-ui/widgets/showcase/js/) and tweaking the display. Once you feel familiar with the library, we recommend following the [getting started guide](https://www.algolia.com/doc/guides/building-search-ui/getting-started/js/).

## Browser support

We support the **last two versions of major browsers** (Chrome, Edge, Firefox, Safari).

Please refer to the [browser support](https://www.algolia.com/doc/guides/building-search-ui/installation/js/#browser-support) section in the documentation to use InstantSearch.js on other browsers.

## Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/guides/building-search-ui/troubleshooting/faq/js/) where you will find answers for the most common issues and gotchas with the library.

## Contributing

We welcome all contributors, from casual to regular 💙

- **Bug report**. Is something not working as expected? [Send a bug report][contributing-bugreport].
- **Feature request**. Would you like to add something to the library? [Send a feature request][contributing-featurerequest].
- **Documentation**. Did you find a typo in the doc? [Open an issue][contributing-newissue] and we'll take care of it.
- **Development**. If you don't know where to start, you can check the open issues that are [tagged easy][contributing-label-easy], the [bugs][contributing-label-bug] or [chores][contributing-label-chore].

To start contributing to code, you need to:

1.  [Fork the project](https://help.github.com/articles/fork-a-repo/)
1.  [Clone the repository](https://help.github.com/articles/cloning-a-repository/)
1.  Install the dependencies: `yarn`

Please read [our contribution process](https://github.com/algolia/instantsearch/blob/master/CONTRIBUTING.md) to learn more.

## License

InstantSearch.js is [MIT licensed][license-url].



[license-url]: LICENSE
[algolia-website]: https://www.algolia.com/?utm_source=instantsearch.js&utm_campaign=repository
[instantsearch-github]: https://github.com/algolia/instantsearch/
[instantsearch-android-github]: https://github.com/algolia/instantsearch-android
[instantsearch-ios-github]: https://github.com/algolia/instantsearch-ios
[contributing-bugreport]: https://github.com/algolia/instantsearch/issues/new?template=BUG_REPORT.yml&labels=triage,Library%3A%20InstantSearch.js
[contributing-featurerequest]: https://github.com/algolia/instantsearch/discussions/new?category=ideas&labels=triage,Library%3A%20InstantSearch.js&title=Feature%20request%3A%20
[contributing-newissue]: https://github.com/algolia/instantsearch/issues/new?labels=triage,Library%3A%20InstantSearch.js
[contributing-label-easy]: https://github.com/algolia/instantsearch/issues?q=is%3Aopen+is%3Aissue+label%3A%22Difficulty%3A+Easy%22+label%3A%22Library%3A%20InstantSearch.js%22
[contributing-label-bug]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug%22+label%3A%22Library%3A%20InstantSearch.js%22
[contributing-label-chore]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Chore%22+label%3A%22Library%3A%20InstantSearch.js%22

---

### Overview (`packages/react-instantsearch-core/README.md`)

<p align="center">
  <a href="https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/react/">
    <img alt="React InstantSearch" src="https://github.com/algolia/instantsearch/blob/master/.github/react-instantsearch-banner.png?raw=true">
  </a>
</p>




- [react-instantsearch-core](#react-instantsearch-core)
  - [Installation](#installation)
  - [Getting started](#getting-started)
  - [API reference](#api-reference)
  - [Documentation](#documentation)
  - [Contributing](#contributing)
  - [License](#license)



# react-instantsearch-core

React InstantSearch Core is an open-source UI library for React that lets you quickly build a search interface in your front-end application.

InstantSearch’s goal is to help you implement awesome search experiences as smoothly as possible by providing a [complete search ecosystem](https://algolia.com/doc/guides/getting-started/how-algolia-works/#the-full-ecosystem). InstantSearch tackles an important part of this vast goal by providing front-end primitives that you can assemble into unique search interfaces.

<p align="center">
  <a href="https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/react/default-themes" title="Edit on CodeSandbox">
    <img alt="Edit on CodeSandbox" src="https://codesandbox.io/static/img/play-codesandbox.svg">
  </a>
</p>

> Note: `react-instantsearch-core` exports renderless components and hooks which can be used for both web and React Native. If you are using React in a web project, we recommend using the package `react-instantsearch` instead, as it includes complete components that render to the DOM.

## Installation

React InstantSearch Core is available on the npm registry. It relies on [`algoliasearch`](https://github.com/algolia/algoliasearch-client-javascript) to communicate with Algolia APIs.

```sh
yarn add algoliasearch react-instantsearch-core
# or
npm install algoliasearch react-instantsearch-core
```

## Getting started

React InstantSearch Core is a headless React library that lets you create an instant search results experience using Algolia’s search API.

Check out our [**Getting Started guide**](https://algolia.com/doc/guides/building-search-ui/getting-started/react/) to start implementing a full-featured search experience with React InstantSearch Core.

## API reference

Check out the [**API reference**](https://www.algolia.com/doc/api-reference/widgets/react/).

## Documentation

The documentation is available on [algolia.com/doc](https://algolia.com/doc/guides/building-search-ui/what-is-instantsearch/react/).

## Contributing

We welcome all contributors, from casual to regular 💙

- **Bug report**. Is something not working as expected? [Send a bug report][contributing-bugreport].
- **Feature request**. Would you like to add something to the library? [Send a feature request][contributing-featurerequest].
- **Documentation**. Did you find a typo in the doc? [Open an issue][contributing-newissue] and we'll take care of it.
- **Development**. If you don't know where to start, you can check the open issues that are [tagged easy][contributing-label-easy], the [bugs][contributing-label-bug] or [chores][contributing-label-chore].

To start contributing to code, you need to:

1.  [Fork the project](https://help.github.com/articles/fork-a-repo/)
1.  [Clone the repository](https://help.github.com/articles/cloning-a-repository/)
1.  Install the dependencies: `yarn`

Please read [our contribution process](https://github.com/algolia/instantsearch/blob/master/CONTRIBUTING.md) to learn more.

## License

React InstantSearch is [MIT licensed](../../LICENSE).



[contributing-bugreport]: https://github.com/algolia/instantsearch/issues/new?template=BUG_REPORT.yml&labels=triage,Library%3A%20React+InstantSearch
[contributing-featurerequest]: https://github.com/algolia/instantsearch/discussions/new?category=ideas&labels=triage,Library%3A%20React+InstantSearch&title=Feature%20request%3A%20
[contributing-newissue]: https://github.com/algolia/instantsearch/issues/new?labels=triage,Library%3A%20React+InstantSearch
[contributing-label-easy]: https://github.com/algolia/instantsearch/issues?q=is%3Aopen+is%3Aissue+label%3A%22Difficulty%3A+Easy%22+label%3A%22Library%3A%20React+InstantSearch%22
[contributing-label-bug]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug%22+label%3A%22Library%3A%20React+InstantSearch%22
[contributing-label-chore]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Chore%22+label%3A%22Library%3A%20React+InstantSearch%22

---

### Overview (`packages/react-instantsearch-nextjs/README.md`)

- [react-instantsearch-nextjs](#react-instantsearch-nextjs)
  - [Installation](#installation)
  - [Usage](#usage)
  - [API](#api)
    - [`<InstantSearchNext>`](#instantsearchnext)
    - [`routing` prop](#routing-prop)
  - [Troubleshooting](#troubleshooting)
  - [Contributing](#contributing)
  - [License](#license)



# react-instantsearch-nextjs

This package provides server-side rendering for [React InstantSearch](https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/react/) that is compatible with [Next.js 13 App Router](https://nextjs.org/docs/app).

## Installation

```sh
yarn add react-instantsearch-nextjs
# or with npm
npm install react-instantsearch-nextjs
```

## Usage

> [!NOTE] You can check this documentation on [Algolia's Documentation website](https://www.algolia.com/doc/guides/building-search-ui/going-further/server-side-rendering/react/#app-router-experimental).

Your search component must be in its own file, and it shouldn't be named `page.js` or `page.tsx`.

To render the component in the browser and allow users to interact with it, include the "use client" directive at the top of your code.

```diff
+'use client';
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import {
  InstantSearch,
  SearchBox,
} from 'react-instantsearch';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

export function Search() {
  return (
    <InstantSearch indexName="YourIndexName" searchClient={searchClient}>
      <SearchBox />
      {/* other widgets */}
    </InstantSearch>
  );
}
```

Import the `<InstantSearchNext>` component from the `react-instantsearch-nextjs` package, and replace the [`<InstantSearch>`](https://www.algolia.com/doc/api-reference/widgets/instantsearch/react/) component with it, without changing the props.

```diff
'use client';
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import {
- InstantSearch,
  SearchBox,
} from 'react-instantsearch';
+import { InstantSearchNext } from 'react-instantsearch-nextjs';

const searchClient = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');

export function Search() {
  return (
-   <InstantSearch indexName="YourIndexName" searchClient={searchClient}>
+   <InstantSearchNext indexName="YourIndexName" searchClient={searchClient}>
      <SearchBox />
      {/* other widgets */}

-   </InstantSearch>
+   </InstantSearchNext>
  );
}
```

To serve your search page at `/search`, create an `app/search` directory. Inside it, create a `page.js` file (or `page.tsx` if you're using TypeScript).

Make sure to [configure your route segment to be dynamic](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamic) so that Next.js generates a new page for each request.

```jsx
// app/search/page.js or app/search/page.tsx
import { Search } from './Search'; // change this with the path to your <Search> component

export const dynamic = 'force-dynamic';

export default function Page() {
  return <Search />;
}
```

You can now visit `/search` to see your server-side rendered search page.

## API

### `<InstantSearchNext>`

The `<InstantSearchNext>` component is a drop-in replacement for the `<InstantSearch>` component. It accepts the same props, and it renders the same UI.

You can check the [InstantSearch API reference](https://www.algolia.com/doc/api-reference/widgets/instantsearch/react/) for more information.

### `routing` prop

As with the `<InstantSearch>` component, you can pass a `routing` prop to the `<InstantSearchNext>` component to customize the routing behavior. The difference here is that `routing.router` takes [the same options as the `historyRouter`](https://www.algolia.com/doc/api-reference/widgets/history-router/react/).

## Troubleshooting

If you're experiencing issues, please refer to the [**Need help?**](https://algolia.com/doc/guides/building-search-ui/what-is-instantsearch/react/#need-help) section of the docs, or [open a new issue](https://github.com/algolia/instantsearch.js/issues/new?assignees=&labels=triage&template=BUG_REPORT.yml).

## Contributing

We welcome all contributors, from casual to regular 💙

- **Bug report**. Is something not working as expected? [Send a bug report][contributing-bugreport].
- **Feature request**. Would you like to add something to the library? [Send a feature request][contributing-featurerequest].
- **Documentation**. Did you find a typo in the doc? [Open an issue][contributing-newissue] and we'll take care of it.
- **Development**. If you don't know where to start, you can check the open issues that are [tagged easy][contributing-label-easy], the [bugs][contributing-label-bug] or [chores][contributing-label-chore].

To start contributing to code, you need to:

1.  [Fork the project](https://help.github.com/articles/fork-a-repo/)
1.  [Clone the repository](https://help.github.com/articles/cloning-a-repository/)
1.  Install the dependencies: `yarn`

Please read [our contribution process](https://github.com/algolia/instantsearch/blob/master/CONTRIBUTING.md) to learn more.

## License

React InstantSearch is [MIT licensed](../../LICENSE).



[contributing-bugreport]: https://github.com/algolia/instantsearch/issues/new?template=BUG_REPORT.yml&labels=triage,Library%3A%20React+InstantSearch
[contributing-featurerequest]: https://github.com/algolia/instantsearch/discussions/new?category=ideas&labels=triage,Library%3A%20React+InstantSearch&title=Feature%20request%3A%20
[contributing-newissue]: https://github.com/algolia/instantsearch/issues/new?labels=triage,Library%3A%20React+InstantSearch
[contributing-label-easy]: https://github.com/algolia/instantsearch/issues?q=is%3Aopen+is%3Aissue+label%3A%22Difficulty%3A+Easy%22+label%3A%22Library%3A%20React+InstantSearch%22
[contributing-label-bug]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug%22+label%3A%22Library%3A%20React+InstantSearch%22
[contributing-label-chore]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Chore%22+label%3A%22Library%3A%20React+InstantSearch%22

---

### Overview (`packages/react-instantsearch-router-nextjs/README.md`)

- [react-instantsearch-router-nextjs](#react-instantsearch-router-nextjs)
  - [Installation](#installation)
  - [Usage](#usage)
  - [API](#api)
  - [Troubleshooting](#troubleshooting)
  - [Contributing](#contributing)
  - [License](#license)



# react-instantsearch-router-nextjs

This package is a router for [React InstantSearch](https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/react/) that is compatible with [Next.js](https://nextjs.org/) routing.

> :warning: **This function cannot be used in conjunction with [`getStaticProps()`](https://nextjs.org/docs/api-reference/data-fetching/get-static-props). Use `getServerSideProps()` or client-side rendering instead.**

## Installation

```sh
yarn add react-instantsearch-router-nextjs
# or with npm
npm install react-instantsearch-router-nextjs
```

## Usage

You need to pass the Next.js router singleton that you can import from `next/router`.

If you are doing SSR with the `getServerState` and `InstantSearchSSRProvider` from `react-instantsearch/server`, you need to pass the `url` prop to `createInstantSearchRouterNext`'s `serverUrl` option :

```js
import singletonRouter from 'next/router';
import { createInstantSearchRouterNext } from 'react-instantsearch-router-nextjs';

export default function Page({ serverState, url }) {
  return (
    <InstantSearchSSRProvider {...serverState}>
      <InstantSearch
        searchClient={searchClient}
        indexName="instant_search"
        routing={{
          router: createInstantSearchRouterNext({
            singletonRouter,
            serverUrl: url,
          }),
        }}
      >
        {/* ... */}
      </InstantSearch>
    </InstantSearchSSRProvider>
  );
}
```

If you are not doing SSR but only CSR, you can omit the `serverUrl` option:

```js
import singletonRouter from 'next/router';
import { createInstantSearchRouterNext } from 'react-instantsearch-router-nextjs';

export default function Page() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="instant_search"
      routing={{ router: createInstantSearchRouterNext({ singletonRouter }) }}
    >
      {/* ... */}
    </InstantSearch>
  );
}
```

Lastly, if you had custom routing logic in your app, you can pass it to the `createInstantSearchRouterNext`'s `routerOptions` option:

```js
import singletonRouter from 'next/router';
import { createInstantSearchRouterNext } from 'react-instantsearch-router-nextjs';

export default function Page({ serverState, url }) {
  return (
    {/* ... */}
      <InstantSearch
        searchClient={searchClient}
        indexName="instant_search"
        routing={{
          router: createInstantSearchRouterNext({
            singletonRouter,
            serverUrl: url,
            routerOptions: {
              createURL: /* ... */,
              parseURL: /* ... */,
            },
          }),
           // if you are using a custom `stateMapping` you can still pass it :
          stateMapping: /* ... */,
        }}
      >
        {/* ... */}
      </InstantSearch>
    {/* ... */}
  );
}
```

## API

The options are :

- `singletonRouter: SingletonRouter`: the required Next.js router singleton.
- `serverUrl?: string`: the URL of the page on the server. Required if you are doing SSR with `getServerState` and `InstantSearchSSRProvider`.
- `routerOptions?: RouterOptions`: the options passed to the `history` router. See [the documentation](https://www.algolia.com/doc/api-reference/widgets/history-router/js/) for more details.

For troubleshooting purposes, some other options are available :

- `beforeStart?: (onUpdate: () => void) => void`: a function called before the router starts. You can use it to inform InstantSearch to update on router events by calling `onUpdate`.
- `beforeDispose?: () => void`: a function called before the router disposes. You can use it to clean up handlers you added in `beforeStart`.
- `beforePopState?: (options: { state: NextHistoryState, ownBeforePopState: BeforePopStateCallback, libraryBeforePopState: BeforePopStateCallback }) => boolean`: a function used by the Next.js router to know whether it should trigger SSR when using back/forward buttons. You can use it to override the default one by writing your own logic. The `ownBeforePopState` is the pre-existing handler that you may have set yourself, and the `libraryBeforePopState` is the default one from the library.

## Troubleshooting

If you're experiencing issues, please refer to the [**Need help?**](https://algolia.com/doc/guides/building-search-ui/what-is-instantsearch/react/#need-help) section of the docs, or [open a new issue](https://github.com/algolia/instantsearch/issues/new?assignees=&labels=triage&template=BUG_REPORT.yml).

## Contributing

We welcome all contributors, from casual to regular 💙

- **Bug report**. Is something not working as expected? [Send a bug report][contributing-bugreport].
- **Feature request**. Would you like to add something to the library? [Send a feature request][contributing-featurerequest].
- **Documentation**. Did you find a typo in the doc? [Open an issue][contributing-newissue] and we'll take care of it.
- **Development**. If you don't know where to start, you can check the open issues that are [tagged easy][contributing-label-easy], the [bugs][contributing-label-bug] or [chores][contributing-label-chore].

To start contributing to code, you need to:

1.  [Fork the project](https://help.github.com/articles/fork-a-repo/)
1.  [Clone the repository](https://help.github.com/articles/cloning-a-repository/)
1.  Install the dependencies: `yarn`

Please read [our contribution process](https://github.com/algolia/instantsearch/blob/master/CONTRIBUTING.md) to learn more.

## License

React InstantSearch is [MIT licensed](../../LICENSE).



[contributing-bugreport]: https://github.com/algolia/instantsearch/issues/new?template=BUG_REPORT.yml&labels=triage,Library%3A%20React+InstantSearch
[contributing-featurerequest]: https://github.com/algolia/instantsearch/discussions/new?category=ideas&labels=triage,Library%3A%20React+InstantSearch&title=Feature%20request%3A%20
[contributing-newissue]: https://github.com/algolia/instantsearch/issues/new?labels=triage,Library%3A%20React+InstantSearch
[contributing-label-easy]: https://github.com/algolia/instantsearch/issues?q=is%3Aopen+is%3Aissue+label%3A%22Difficulty%3A+Easy%22+label%3A%22Library%3A%20React+InstantSearch%22
[contributing-label-bug]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug%22+label%3A%22Library%3A%20React+InstantSearch%22
[contributing-label-chore]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Chore%22+label%3A%22Library%3A%20React+InstantSearch%22

---

### Overview (`packages/react-instantsearch/README.md`)

<p align="center">
  <a href="https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/react/">
    <img alt="React InstantSearch" src="https://github.com/algolia/instantsearch/blob/master/.github/react-instantsearch-banner.png?raw=true">
  </a>
</p>




- [react-instantsearch](#react-instantsearch)
  - [Why](#why)
  - [Installation](#installation)
  - [Getting started](#getting-started)
  - [Documentation](#documentation)
  - [Playground](#playground)
  - [Contributing](#contributing)
  - [License](#license)



# react-instantsearch

React InstantSearch is an open-source React library that lets you create an instant search result experience using [Algolia][algolia-website]’s search API. It is part of the InstantSearch family:

**React InstantSearch** | [InstantSearch.js][instantsearch-github] | [Vue InstantSearch][instantsearch-github] | [InstantSearch Android][instantsearch-android-github] | [InstantSearch iOS][instantsearch-ios-github]

## Why

You should be using React InstantSearch if you want to:

- Design search experiences with best practices
- Customize your components at will
- Follow React principles

Note: If you are working with React Native, or otherwise do not use the DOM, check out `react-instantsearch-core` instead.

## Installation

React InstantSearch is available on the npm registry. It relies on [`algoliasearch`](https://github.com/algolia/algoliasearch-client-javascript) to communicate with Algolia APIs.

```sh
yarn add algoliasearch react-instantsearch
# or
npm install algoliasearch react-instantsearch
```

## Getting started

Using React InstantSearch is as simple as adding these components to your app:

```javascript
import React from 'react';
import ReactDOM from 'react-dom';
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import { InstantSearch, SearchBox, Hits } from 'react-instantsearch';

const searchClient = algoliasearch(
  'latency',
  '6be0576ff61c053d5f9a3225e2a90f76'
);

const App = () => (
  <InstantSearch indexName="bestbuy" searchClient={searchClient}>
    <SearchBox />
    <Hits />
  </InstantSearch>
);
```

<p align="center">
  <a href="https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/react/default-theme" title="Edit on CodeSandbox">
    <img alt="Edit on CodeSandbox" src="https://codesandbox.io/static/img/play-codesandbox.svg">
  </a>
</p>

To learn more about the library, follow the [getting started guide][doc-getting-started].

## Documentation

The documentation is available on [algolia.com/doc][doc].

## Playground

You can get to know React InstantSearch on [this playground][doc-playground].

Start by [adding components][doc-getting-started] and tweaking the display. Once you get more familiar with the library, you can learn more advanced concepts in [our guides][doc-guides].

## Contributing

We welcome all contributors, from casual to regular 💙

- **Bug report**. Is something not working as expected? [Send a bug report][contributing-bugreport].
- **Feature request**. Would you like to add something to the library? [Send a feature request][contributing-featurerequest].
- **Documentation**. Did you find a typo in the doc? [Open an issue][contributing-newissue] and we'll take care of it.
- **Development**. If you don't know where to start, you can check the open issues that are [tagged easy][contributing-label-easy], the [bugs][contributing-label-bug] or [chores][contributing-label-chore].

To start contributing to code, you need to:

1.  [Fork the project](https://help.github.com/articles/fork-a-repo/)
1.  [Clone the repository](https://help.github.com/articles/cloning-a-repository/)
1.  Install the dependencies: `yarn`

Please read [our contribution process](https://github.com/algolia/instantsearch/blob/master/CONTRIBUTING.md) to learn more.

## License

React InstantSearch is [MIT licensed](../../LICENSE).



[doc]: https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/react/
[doc-getting-started]: https://www.algolia.com/doc/guides/building-search-ui/getting-started/react/
[doc-guides]: https://www.algolia.com/doc/guides/building-search-ui/going-further/server-side-rendering/react/
[doc-playground]: https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/react/default-theme
[algolia-website]: https://www.algolia.com/
[instantsearch-github]: https://github.com/algolia/instantsearch
[instantsearch-android-github]: https://github.com/algolia/instantsearch-android
[instantsearch-ios-github]: https://github.com/algolia/instantsearch-ios
[contributing-bugreport]: https://github.com/algolia/instantsearch/issues/new?template=BUG_REPORT.yml&labels=triage,Library%3A%20React+InstantSearch
[contributing-featurerequest]: https://github.com/algolia/instantsearch/discussions/new?category=ideas&labels=triage,Library%3A%20React+InstantSearch&title=Feature%20request%3A%20
[contributing-newissue]: https://github.com/algolia/instantsearch/issues/new?labels=triage,Library%3A%20React+InstantSearch
[contributing-label-easy]: https://github.com/algolia/instantsearch/issues?q=is%3Aopen+is%3Aissue+label%3A%22Difficulty%3A+Easy%22+label%3A%22Library%3A%20React+InstantSearch%22
[contributing-label-bug]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Bug%22+label%3A%22Library%3A%20React+InstantSearch%22
[contributing-label-chore]: https://github.com/algolia/instantsearch/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+Chore%22+label%3A%22Library%3A%20React+InstantSearch%22

---

### Overview (`packages/vue-instantsearch/README.md`)

- [Vue InstantSearch](#vue-instantsearch)
- [Documentation](#documentation)
- [Installation](#installation)
- [Troubleshooting](#troubleshooting)
- [Contributing, dev, release](#contributing-dev-release)



[![Vue InstantSearch logo][logo]][website]

InstantSearch projects: **Vue InstantSearch** | [InstantSearch.js][instantsearch-github] | [React InstantSearch][instantsearch-github] | [InstantSearch Android][instantsearch-android-github] | [InstantSearch iOS][instantsearch-ios-github].

## Vue InstantSearch

> ⚡ Lightning-fast search for Vue.js apps

Built by [Algolia][algolia-website].

This repository holds the code for the Vue InstantSearch project.

## Documentation

There's a dedicated documentation available at [www.algolia.com/doc/guides/building-search-ui/getting-started/vue][website].

## Installation

Vue InstantSearch is available in the npm registry. Install it:

```sh
# with npm
npm install --save vue-instantsearch

# with yarn
yarn add vue-instantsearch
```

To learn more about the usage, follow our [getting started guide][getting-started-guide].

## Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our [FAQ](https://www.algolia.com/doc/guides/building-search-ui/troubleshooting/faq/vue/) where you will find answers for the most common issues and gotchas with the library.

## Contributing, dev, release

We welcome all contributors, from casual to regular. You are only one command away to start the developer environment, [read our CONTRIBUTING guide](CONTRIBUTING.md).

[logo]: vue-instantsearch-readme.png
[website]: https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/vue/
[getting-started-guide]: https://www.algolia.com/doc/guides/building-search-ui/getting-started/vue/
[algolia-website]: https://www.algolia.com/
[instantsearch-github]: https://github.com/algolia/instantsearch
[instantsearch-android-github]: https://github.com/algolia/instantsearch-android
[instantsearch-ios-github]: https://github.com/algolia/instantsearch-ios

---

### Overview (`tests/common/README.md`)

# Common test suites

## Table of contents

- [Adding new tests in an existing test suite](#adding-new-tests-in-an-existing-test-suite)
- [Testing a new widget](#testing-a-new-widget)

To ensure InstantSearch widgets behave similarly in InstantSearch.js, React InstantSearch, and Vue InstantSearch, we're using framework-agnostic tests suites to assert behaviors that should be consistent across flavors.

Each test suite is a function that exposes:

- **A setup**, which is the _arrange_ code passed by each flavor to set up test cases
- **An act**, to isolate the code that prepares the assertion. This is necessary when working with UI libraries like React.

> **Note** The setup code is defined in the `common-{widgets|connectors|shared}.test.{tsx|js}` file present in each package.

Tests that only apply to specific flavors belong to their relevant packages, as normal test suites. For reference, check out the common test suite of the breadcrumb widget:

- [Common scenarios](../../tests/common/widgets/breadcrumb)
- Flavor-specific tests:
  - [InstantSearch.js](../../packages/instantsearch.js/src/widgets/breadcrumb/__tests__)
  - [React InstantSearch](../../packages/react-instantsearch/src/widgets/__tests__)
  - [Vue InstantSearch](../../packages/vue-instantsearch/src/components/__tests__)

> **Note** Flavor-specific tests should be the exception. They should either cover inconsistencies between flavors that should go away in a next major, or assert flavor-specific behavior or APIs.

## Adding new tests in an existing test suite

If you need to add a new test for an existing widget in an existing test suite, you can add a new `test` block in the dedicated file and write your test here. This new test will run with every flavor.

```js
test('behaves as expected', async () => {
  // 1. Arrange
  // This leverages the `setup` function passed by each flavor.
  // You can pass options to InstantSearch (index name, search client)
  // and to the widgets.
  await setup({
    instantSearchOptions: {
      indexName: 'indexName',
      searchClient,
    },
    widgetParams: { attributes: hierarchicalAttributes },
  });

  // 2. Act
  // Any interaction must be wrapped in `act`, which is passed by each flavor.
  // You'll need to use `wait` before asserting as renders are asynchronous.
  await act(async () => {
    await wait(0);
  });

  // 3. Assert
  // You can assert anything here based on the `container` of the widget.
  expect(document.querySelector('.ais-Breadcrumb')).toMatchInlineSnapshot(`
    
  `);
});
```

> **Note** If you need to use Testing Library queries, you can import [`screen`](https://testing-library.com/docs/queries/about#screen) from [`@testing-library/dom`](https://testing-library.com/docs/dom-testing-library/intro/) and call queries on it.

## Testing a new widget

If you created a new widget and you want to create common tests for them, the process is as follows:

- In [`tests/common/widgets`](tests/common/widgets), create a directory with the name of your widget (in kebab-case):
  - Create a file with the name of your test suite (e.g., `optimistic-ui.ts`, `options.ts`). In doubt, refer to existing test suites for existing widgets.
  - Create an `index.ts` file that exports a factory function to create your of test suite collection. You can copy one from an existing widget's test suite and modify it to suit your own widget.
- In your new test suite, export a factory function to create your test suite. You can copy one from an existing widget's test suite and modify it to suit your own widget.
- In each `common.test.{tsx|js}` file (in each package), import your test suite collection from `@instantsearch/tests`, and call it at the end of the file with the necessary test setup. You can copy one from the same file and modify it to suit your own widget.

---

### Overview (`tests/e2e/README.md`)

# End-to-end test suite for InstantSearch

This package contains the end-to-end test suite for all InstantSearch flavors.

## Installation

The workspace automatically links the dependencies when you run `yarn` at the root of the monorepo.

## Running the test suite

In addition to the test suite, this package contains two [WebdriverIO](https://webdriver.io) configurations:

- `local`: run the test suite on [Chrome browser](https://google.com/chrome) on your local machine.
- `saucelabs`: run the test suite on multiple browsers on the [Sauce Labs service](https://saucelabs.com).

All configurations will run a static web server on your machine on port `5000` to serve the content of the `website` directory in your project, containing the InstantSearch demos to run our tests against.

### Locally

To run the test suite locally create a `wdio.local.conf.js` file in your project root and import the `local` configuration.

```js
const { local } = require('instantsearch-e2e-tests');

exports.config = local;
```

Then execute the following command to run the test suite.

```bash
./node_modules/.bin/wdio wdio.local.conf.js
```

### On Sauce Labs

To run the test suite on Sauce Labs create a `wdio.saucelabs.conf.js` file in your project root and import the `saucelabs` configuration.

```js
const { saucelabs } = require('instantsearch-e2e-tests');

exports.config = saucelabs;
```

#### Credentials

You'll need a username and access key to be able to run the test suite on Sauce Labs. You can find them in the User **Profile** > **User Settings** section of your Sauce Labs dashboard.

`instantsearch-e2e-tests` will read the username and access key from the `SAUCE_USERNAME` and `SAUCE_ACCESS_KEY` environment variables respectively. More information about [setting up environment variables for Sauce Labs](https://wiki.saucelabs.com/display/DOCS/Best+Practice%3A+Use+Environment+Variables+for+Authentication+Credentials).

Alternatively you can store them in a `.env` file at the root of your project, `instantsearch-e2e-tests` will automatically load them using [dotenv](https://github.com/motdotla/dotenv). **But don't forget to add this file to your `.gitignore`.**

Once your config file created and your credentials set you can execute the following command to run the test suite.

```bash
./node_modules/.bin/wdio wdio.saucelabs.conf.js
```

## Overriding configuration

The default configuration can easily be overridden if you need to change some project specific settings.

```js
const { local } = require('instantsearch-e2e-tests');

exports.config = {
  ...local,
  /*
   * Run local tests on Firefox instead of Chrome
   */
  capabilities: [
    {
      browserName: 'firefox',
    },
  ],
};
```

## Sending reports to CircleCI

CircleCI can [read JUnit XML test metadata files](https://circleci.com/docs/2.0/collect-test-data/) to provide insights on the stability of the test suite. To enable this feature, you can add the following key to your e2e job in **.circleci/config.yml**:

```yaml
test_e2e:
  # ...
  steps:
    # ...
    - store_test_results:
      path: junit/wdio
```

---

### Overview (`examples/js/e-commerce-umd/README.md`)

# E-commerce UMD demo

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/js/e-commerce-umd)

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Get started

To run this project locally, install the dependencies and run the local server:

```sh
npm install
npm start
```

Alternatively, you may use [Yarn](https://yarnpkg.com/):

```sh
yarn
yarn start
```

Open http://localhost:3000 to see your app.

## Notes

This application is made for two reasons:

- end to end tests
- code that can be reused on a regular InstantSearch project

This means that some of the setup won't work out of the box on every machine. This requires that you:

- use a UNIX system (like Mac or Linux)
- build the library before starting this example:

```sh
yarn install && yarn build && (cd examples/js/e-commerce-umd/ && yarn start)
```

Alternatively to that, you can remove the `alias` in package.json for `instantsearch.js` to `../../`

---

### Overview (`examples/js/e-commerce/README.md`)

# E-commerce demo

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/js/e-commerce)

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Get started

To run this project locally, install the dependencies and run the local server:

```sh
npm install
npm start
```

Alternatively, you may use [Yarn](https://yarnpkg.com/):

```sh
yarn
yarn start
```

Open http://localhost:3000 to see your app.

## Notes

This application is made for two reasons:

- end to end tests
- code that can be reused on a regular InstantSearch project

This means that some of the setup won't work out of the box on every machine. This requires that you:

- use a UNIX system (like Mac or Linux)
- build the library before starting this example:

```sh
yarn install && yarn build && (cd examples/e-commerce/ && yarn start)
```

Alternatively to that, you can remove the `alias` in package.json for `instantsearch.js` to `../../`

---

### Overview (`examples/js/getting-started/README.md`)

# Getting started demo

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/js/getting-started)

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Get started

To run this project locally, install the dependencies and run the local server:

```sh
npm install
npm start
```

Alternatively, you may use [Yarn](https://http://yarnpkg.com/):

```sh
yarn
yarn start
```

Open http://localhost:3000 to see your app.

---

### Overview (`examples/js/media/README.md`)

# Media demo

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/js/media)

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Get started

To run this project locally, install the dependencies and run the local server:

```sh
npm install
npm start
```

Alternatively, you may use [Yarn](https://http://yarnpkg.com/):

```sh
yarn
yarn start
```

Open http://localhost:3000 to see your app.

---

### Overview (`examples/js/query-suggestions/README.md`)

# Query suggestions demo

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/js/query-suggestions)

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Get started

To run this project locally, install the dependencies and run the local server:

```sh
npm install
npm start
```

Alternatively, you may use [Yarn](https://http://yarnpkg.com/):

```sh
yarn
yarn start
```

Open http://localhost:3000 to see your app.

---

### Overview (`examples/react/getting-started/README.md`)

# react-instantsearch-app

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/react/getting-started)

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Get started

To run this project locally, install the dependencies and run the local server:

```sh
npm install
npm start
```

Alternatively, you may use [Yarn](https://http://yarnpkg.com/):

```sh
yarn
yarn start
```

Open http://localhost:3000 to see your app.

---

### Overview (`examples/react/next-app-router/README.md`)

This example shows how to do server side rendering with next.js (App Router) and InstantSearchNext. There's a live example here: https://codesandbox.io/p/devbox/github/algolia/instantsearch.js/tree/master/examples/react/next-app-router.

[](https://codesandbox.io/p/devbox/github/algolia/instantsearch.js/tree/master/examples/react/next-app-router)

## Clone the example

```sh
curl https://codeload.github.com/algolia/instantsearch/tar.gz/master | tar -xz --strip=3 instantsearch-master/examples/react/next-app-router
```

## Start the example

```sh
yarn install --no-lockfile
yarn run dev
```

Read more about React InstantSearchNext [in our documentation](https://www.algolia.com/doc/guides/building-search-ui/going-further/server-side-rendering/react/#app-router-experimental).

---

### Overview (`examples/react/next-routing/README.md`)

This example shows how to do server side rendering with next.js and React InstantSearch. There's a live example here: https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/react/next.

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/react/next-routing)

## Clone the example

```sh
curl https://codeload.github.com/algolia/instantsearch/tar.gz/master | tar -xz --strip=3 instantsearch-master/examples/react/next-routing
```

## Start the example

```sh
yarn install --no-lockfile
yarn run dev
```

Read more about React InstantSearch [in our documentation](https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/react/).

---

### Overview (`examples/react/next/README.md`)

This example shows how to do server side rendering with next.js and React InstantSearch. There's a live example here: https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/react/next.

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/react/next)

## Clone the example

```sh
curl https://codeload.github.com/algolia/instantsearch/tar.gz/master | tar -xz --strip=3 instantsearch-master/examples/react/next
```

## Start the example

```sh
yarn install --no-lockfile
yarn run dev
```

Read more about React InstantSearch [in our documentation](https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/react/).

---

### Overview (`examples/react/query-suggestions/README.md`)

# Query suggestions demo

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/react/query-suggestions)

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Get started

To run this project locally, install the dependencies and run the local server:

```sh
npm install
npm start
```

Alternatively, you may use [Yarn](https://http://yarnpkg.com/):

```sh
yarn
yarn start
```

Open http://localhost:3000 to see your app.

---

### Overview (`examples/react/react-native/README.md`)

# React InstantSearch with React Native

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/react/react-native)

This example shows how to use React InstantSearch with React Native (Expo). Because `react-instantsearch-core` ships headless hooks (no DOM widgets), every widget below is built from those hooks and plain React Native primitives — no `react-native-svg` or other native UI dependencies required.

## Widgets

Each widget lives in its own file under [`src/`](./src) so it can be copied into your own app:

| Widget | File | Hook / connector |
| --- | --- | --- |
| Search box | `SearchBox.tsx` | `useSearchBox` |
| Infinite scroll results | `InfiniteHits.tsx` | `useInfiniteHits` |
| Highlighting | `Highlight.tsx` | `getHighlightedParts` |
| Snippeting | `Snippet.tsx` | `getHighlightedParts` (`_snippetResult`) |
| Star rating (display) | `Rating.tsx` | — |
| Category drill-down | `HierarchicalMenu.tsx` | `useHierarchicalMenu` |
| Searchable brand facet | `RefinementList.tsx` | `useRefinementList` |
| Price range inputs | `PriceRange.tsx` | `useRange` |
| Free-shipping switch | `ToggleRefinement.tsx` | `useToggleRefinement` |
| Ratings facet | `RatingMenu.tsx` | `useConnector(connectRatingMenu)` |
| Sort between replicas | `SortBy.tsx` | `useSortBy` |
| Result count / timing | `Stats.tsx` | `useStats` |
| Active refinement chips | `CurrentRefinements.tsx` | `useCurrentRefinements` |
| Filters modal (composes the facets) | `Filters.tsx` | `useClearRefinements`, `useCurrentRefinements` |
| Empty state | `NoResults.tsx` | `useInstantSearch`, `useClearRefinements` |

> `RatingMenu` shows the escape hatch for connectors that don't yet have a
> dedicated hook: wrap the vanilla `connectRatingMenu` connector with
> `useConnector`.

## Recommend

Algolia Recommend runs through the same `searchClient` (the v5 `algoliasearch/lite` client exposes `getRecommendations`), so no extra client is needed. Tapping a product opens `ProductDetail.tsx`, which shows three model-backed carousels; a "Trending" carousel also sits atop the results list.

| Widget | File | Hook |
| --- | --- | --- |
| Related products | `Recommend.tsx` | `useRelatedProducts` |
| Frequently bought together | `Recommend.tsx` | `useFrequentlyBoughtTogether` |
| Looking similar | `Recommend.tsx` | `useLookingSimilar` |
| Trending items | `Recommend.tsx` | `useTrendingItems` |

`Carousel.tsx` and `ProductCard.tsx` are the presentational pieces shared by all four.

## Query suggestions & recent searches

Focusing the search box reveals `Suggestions.tsx`. Suggestions are fetched through a nested `<Index indexName="instant_search_demo_query_suggestions">` + `useHits`, so they ride along in the same multi-index request as the main search — no second InstantSearch instance. Recent searches are persisted to `AsyncStorage` (`recentSearches.ts`) since `localStorage` doesn't exist in React Native.

## Routing & analytics adapters

The DOM-coupled parts of InstantSearch are replaced with React Native equivalents:

| Concern | File | What it does |
| --- | --- | --- |
| Routing | `router.ts` | A custom `Router` persisting UI state to `AsyncStorage` (the built-in history router needs `window.history`/URLs). State is hydrated before `<InstantSearch>` mounts because `router.read()` is synchronous. |
| Insights | `insights.ts` | A minimal Insights client that `POST`s events with `fetch` and keeps the user token in memory, avoiding the CDN `<script>` and `document.cookie`. Wired via `insights={{ insightsClient, insightsInitParams: { useCookie: false } }}`; clicks are reported from `InfiniteHits.tsx` via `sendEvent`. |

> This example depends on `@react-native-async-storage/async-storage` for the
> routing and recent-searches persistence above.

## Clone the example

```sh
curl https://codeload.github.com/algolia/instantsearch/tar.gz/master | tar -xz --strip=3 instantsearch-master/examples/react/react-native
```

## Start the example

```sh
yarn install --no-lockfile
yarn run start
```

Read more about React InstantSearch [in our documentation](https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/react/).

---

### Overview (`examples/react/ssr/README.md`)

# React InstantSearch | Server-side rendering

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/react/ssr)

This example shows how to do server-side rendering with React InstantSearch.

## Clone the example

```sh
curl https://codeload.github.com/algolia/instantsearch/tar.gz/master | tar -xz --strip=3 instantsearch-master/examples/react/ssr
```

## Start the example

```sh
yarn install --no-lockfile
yarn start
```

---

### Overview (`examples/vue/default-theme/README.md`)

# default-theme

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/vue/default-theme)

## Project setup

```
yarn install
```

### Compiles and hot-reloads for development

```
yarn run dev
```

### Compiles and minifies for production

```
yarn run build
```

---

### Overview (`examples/vue/e-commerce/README.md`)

# E-commerce demo

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/vue/e-commerce)

## Project setup

```
yarn install
```

### Compiles and hot-reloads for development

```
yarn run dev
```

### Compiles and minifies for production

```
yarn run build
```

---

### Overview (`examples/vue/getting-started/README.md`)

# vue-instantsearch-app

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/vue/getting-started)

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Project setup

```
yarn install
```

### Compiles and hot-reloads for development

```
yarn run dev
```

### Compiles and minifies for production

```
yarn run build
```

---

### Overview (`examples/vue/media/README.md`)

# media

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/vue/media)

## Project setup

```
yarn install
```

### Compiles and hot-reloads for development

```
yarn run dev
```

### Compiles and minifies for production

```
yarn run build
```

---

### Overview (`examples/vue/nuxt/README.md`)

# nuxt

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/vue/nuxt)

> Vue InstantSearch & Nuxt

## Build Setup

```bash
# install dependencies
$ yarn install

# serve with hot reload at localhost:3000
$ yarn run dev

# build for production and launch server
$ yarn run build
$ yarn start

# generate static project
$ yarn run generate
```

For detailed explanation on how things work, checkout [Nuxt.js docs](https://nuxtjs.org).

---

### Overview (`examples/vue/ssr/README.md`)

# ssr

[](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/vue/ssr)

## Project setup

```
yarn install
```

### Compiles and hot-reloads for development

```
yarn run serve
```

### Compiles and minifies for production

```
yarn run build
```

### Run your tests

```
yarn run test
```

### Lints and fixes files

```
yarn run lint
```

---

### Overview (`packages/algoliasearch-helper/examples/readme.md`)

The examples moved to [codepen](http://codepen.io/collection/nwWJbe/).

---

### Overview (`examples/vue/nuxt/layouts/README.md`)

# LAYOUTS

**This directory is not required, you can delete it if you don't want to use it.**

This directory contains your Application Layouts.

More information about the usage of this directory in [the documentation](https://nuxtjs.org/guide/views#layouts).

---

### Overview (`examples/vue/nuxt/pages/README.md`)

# PAGES

This directory contains your Application Views and Routes. The framework reads all the `*.vue` files inside this directory and create the router of your application.

More information about the usage of this directory in [the documentation](https://nuxtjs.org/guide/routing).

---

### Overview (`examples/vue/nuxt/static/README.md`)

# STATIC

**This directory is not required, you can delete it if you don't want to use it.**

This directory contains your static files. Each file inside this directory is mapped to `/`.

Example: `/static/robots.txt` is mapped as `/robots.txt`.

More information about the usage of this directory in [the documentation](https://nuxtjs.org/guide/assets#static).

---

### Overview (`packages/instantsearch.js/scripts/transforms/README.md`)

## Codemods

These codemods (code transformers) can be ran with [jscodeshift]((https://github.com/facebook/jscodeshift).

### `addWidget-to-addWidgets`

This will replace calls of `addWidget(widget)` to `addWidgets([widget])`, as well as `removeWidget(widget) to `removeWidgets([widget])`.

```
npx @codeshift/cli --packages 'instantsearch-codemods#addWidget-to-addWidgets' <path>
```

### Notes

If you are using a formatter or a linter, make sure to run its autofixing after this transformation, since code can be formatted differently after it has been transformed. In our repository, that would be:

```
yarn format
```

---

### Overview (`packages/create-instantsearch-app/src/templates/Autocomplete/README.md`)

# {{name}}

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Get started

To run this project locally, install the dependencies and run the local server:

```sh
npm install
npm start
```

Alternatively, you may use [Yarn](https://http://yarnpkg.com/):

```sh
yarn
yarn start
```

Open http://localhost:3000 to see your app.

---

### Overview (`packages/create-instantsearch-app/src/templates/InstantSearch.js widget/README.md`)

# {{ name }}

{{ description }}

---

[](./LICENSE) [](https://npmjs.org/package/{{ packageName }})

## Install

```bash
npm install {{ packageName }}
# or
yarn add {{ packageName }}
```

## Widget

### Usage

```js
import instantsearch from 'instantsearch.js';
import algoliasearch from 'algoliasearch/lite';
import { {{ camelCaseName }} } from '{{ packageName }}';

const searchClient = algoliasearch('appId', 'apiKey');

const search = instantsearch({
  indexName: 'indexName',
  searchClient,
});

search.addWidgets([
  {{ camelCaseName }}({
    // widget parameters
  }),
]);

search.start();
```

### Options

| Option | Type | Required | Default | Description |
| :-- | :-- | :-- | :-- | --- |
| [`container`](#container) | `string` or `HTMLElement` | true | - | The element to insert the widget into. |
| [`option1`](#option1) | `...` | true | - | REPLACE WITH THE DESCRIPTION FOR THIS OPTION |

#### container

> `string | Element` | **required**

The element to insert the widget into.

This can be either a valid CSS Selector:

```js
{{ camelCaseName }}({
  container: '#{{ name }}',
  // ...
});
```

or an `HTMLElement`:

```js
{{ camelCaseName }}({
  container: document.querySelector('#{{ name }}'),
  // ...
});
```

#### option1

> `...` | **required**

REPLACE WITH THE DESCRIPTION FOR THIS OPTION

```js
{{ camelCaseName }}({
  option1: 'value',
  // ...
});
```

## Connector

### Usage

```js
import { connect{{ pascalCaseName }} } from '{{ packageName }}';

// 1. Create a render function
const render{{ pascalCaseName }} = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const custom{{ pascalCaseName }} = connect{{ pascalCaseName }}(
  render{{ pascalCaseName }}
);

// 3. Instantiate
search.addWidgets([
  custom{{ pascalCaseName }}({
    // instance params
  }),
]);
```

### Options

#### option1

> `...`

REPLACE WITH THE DESCRIPTION FOR THIS RENDERING ITEM

```js
const render{{ pascalCaseName }} = (renderOptions, isFirstRender) => {
  // show how to use this render option
};

const custom{{ pascalCaseName }} = connect{{ pascalCaseName }}(
  render{{ pascalCaseName }},
);

search.addWidgets([
  custom{{pascalCaseName }}({
    // ...
  }),
]);
```

#### widgetParams

> `object`

All original widget options forwarded to the render function.

```js
const render{{ pascalCaseName }} = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;
  widgetParams.container.innerHTML = '...';
};

const custom{{ pascalCaseName }} = connect{{ pascalCaseName }}(
  render{{ pascalCaseName }},
);

search.addWidgets([
  custom{{ pascalCaseName }}({
    container: document.querySelector('#{{ name }}'),
    // ...
  }),
]);
```

## Contributing

To start contributing to code, you need to:

1. [Fork the project](https://docs.github.com/en/get-started/quickstart/fork-a-repo)
2. [Clone the repository](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository-from-github/cloning-a-repository)
3. Install the dependencies: `yarn`
4. Run the development mode: `yarn start`

Please read [our contribution process](./CONTRIBUTING.md) to learn more.

---

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

---

### Overview (`packages/create-instantsearch-app/src/templates/InstantSearch.js/README.md`)

# {{name}}

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Get started

To run this project locally, install the dependencies and run the local server:

```sh
npm install
npm start
```

Alternatively, you may use [Yarn](https://http://yarnpkg.com/):

```sh
yarn
yarn start
```

Open http://localhost:3000 to see your app.

---

### Overview (`packages/create-instantsearch-app/src/templates/JavaScript Client/README.md`)

# {{name}}

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Get started

To run this project locally, install the dependencies and run the local server:

```sh
npm install
npm start
```

Alternatively, you may use [Yarn](https://http://yarnpkg.com/):

```sh
yarn
yarn start
```

Open http://localhost:3000 to see your app.

---

### Overview (`packages/create-instantsearch-app/src/templates/JavaScript Helper/README.md`)

# {{name}}

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Get started

To run this project locally, install the dependencies and run the local server:

```sh
npm install
npm start
```

Alternatively, you may use [Yarn](https://http://yarnpkg.com/):

```sh
yarn
yarn start
```

Open http://localhost:3000 to see your app.

---

### Overview (`packages/create-instantsearch-app/src/templates/React InstantSearch Native/README.md`)

# {{name}}

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Get started

To run this project locally, install the dependencies and run the local server:

```sh
npm install
npm start
```

Alternatively, you may use [Yarn](https://http://yarnpkg.com/):

```sh
yarn
yarn start
```

---

### Overview (`packages/create-instantsearch-app/src/templates/React InstantSearch/README.md`)

# {{name}}

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Get started

To run this project locally, install the dependencies and run the local server:

```sh
npm install
npm start
```

Alternatively, you may use [Yarn](https://http://yarnpkg.com/):

```sh
yarn
yarn start
```

---

### Overview (`packages/create-instantsearch-app/src/templates/Vue InstantSearch with Vue 3/README.md`)

# {{name}}

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Get started

To run this project locally, install the dependencies and run the local server:

```sh
npm install
npm start
```

Alternatively, you may use [Yarn](https://http://yarnpkg.com/):

```sh
yarn
yarn start
```

Open http://localhost:3000 to see your app.

---

### Overview (`packages/create-instantsearch-app/src/templates/Vue InstantSearch/README.md`)

# {{name}}

_This project was generated with [create-instantsearch-app](https://github.com/algolia/instantsearch/tree/master/packages/create-instantsearch-app) by [Algolia](https://algolia.com)._

## Get started

To run this project locally, install the dependencies and run the local server:

```sh
npm install
npm start
```

Alternatively, you may use [Yarn](https://http://yarnpkg.com/):

```sh
yarn
yarn start
```

Open http://localhost:3000 to see your app.

---

### Overview (`packages/instantsearch-ui-components/src/lib/markdown-to-jsx/README.md`)

Vendored copy of [`markdown-to-jsx`](https://github.com/quantizor/markdown-to-jsx) v7.7.15 (MIT, see `LICENSE`), taken from the original TypeScript embedded in the npm package's source map.

Changes from upstream:

- React types are replaced by the shared `Renderer` types, so the module has no `react` import, not even as a type.
- `createElement` must be passed in options (no `React.createElement` fallback).
- The `<Markdown>` React component and the default export are removed.
- Raw HTML parsing is removed: the `htmlBlock` and `htmlSelfClosing` rules, the `disableParsingRawHTML` option and the state, types and helpers that only they used. HTML comments are still dropped.
- Formatted and linted with the repo's config, and type-checked under its strict TypeScript config: non-null assertions, `any` casts for dynamic indexing, `null` added to a few declared types, unused parameters prefixed with `_`, `var` replaced by `let`/`const`, a sparse array literal written with an explicit `undefined`, `LOOKAHEAD` renamed to `lookahead`, type parameters renamed to the `T` prefix convention, and `eslint-disable` comments for the dev-only `console.warn` calls, the namespace and a deprecated type. The emitted JavaScript is otherwise unchanged.

---

### Packages Create Instantsearch App Docs Custom Templates (`packages/create-instantsearch-app/docs/custom-templates.md`)

# Creating a custom template

Besides all the InstantSearch templates provided, the Create InstantSearch API enables you to create your own template.

<details>
  <summary><strong>Contents</strong></summary>




- [Defining the template](#defining-the-template)
  - [`libraryName`](#libraryname)
  - [`tasks`](#tasks)
- [Injecting values to the template](#injecting-values-to-the-template)
- [Using the template](#using-the-template)
- [Examples](#examples)



</details>

## Defining the template

Once you've created a project directory, you can turn it into a template by adding a file `.template.js` at its root. This is the configuration file that drives `createInstantSearchApp()` to bootstrap your application.

This definition file returns a object with several properties.

<h6 align="center">.template.js</h6>

```javascript
const { execSync } = require('child_process');

module.exports = {
  libraryName: 'react-instantsearch',
  tasks: {
    install(config) {
      execSync(`cd ${config.path} && npm install`);
    },
    teardown(config) {
      console.log('Begin by running: npm start');
    },
  },
};
```

### `libraryName`

> `string` (optional) | no default

The name of the [npm](https://www.npmjs.com) library to fetch versions for.

### `tasks`

> `object` | defaults as follows

The tasks are hooks that define your [application generation lifecycle](#lifecycle). Each of these hooks are functions which receives the [app configuration](#configuration-object) as parameters. You can use this configuration to drive the application generation.

#### `setup(config: object)`

> No default

Can be leveraged to check the project requirements.

#### `build(config: object)`

> Defaults to copying and injecting the values

Can be leveraged to generate the project differently.

#### `install(config: object)`

> No default

Can be leveraged to install dependencies with a package manager.

#### `clean(config: object)`

> Defaults to deleting the project which installation has failed

Can be leveraged to warn the user that the installation has failed.

#### `teardown(config: object)`

> No default

Can be leveraged to display instructions to run the app.

<h6 align="center" id="lifecycle">Application generation lifeycle</h6>



<h6 align="center" id="configuration-object"><code>config</code> object</h6>

```js
{
  name: 'app-name',
  path: '/dev/app-name',
  template: 'InstantSearch.js',
  libraryVersion: '2.9.0',
  appId: 'APP_ID',
  apiKey: 'API_KEY',
  indexName: 'INDEX_NAME',
  attributesToDisplay: ['title', 'description'],
  installation: true,
  silent: false,
}
```

## Injecting values to the template

By default, the `build` task supports the [Handlebars](https://handlebarsjs.com) syntax to inject values passed to Create InstantSearch App. You can explicitly suffix the template files with `.hbs` or leave them as is (`.js` in this case).

<h6 align="center">App.js.hbs</h6>

```handlebars
import React, { Component } from 'react';
import algoliasearch from 'algoliasearch/lite';
import {
  InstantSearch,
  Hits,
  SearchBox,
  {{#if attributesToDisplay}}
  Highlight,
  {{/if}}
} from 'react-instantsearch-dom';

const searchClient = algoliasearch(
  '{{appId}}',
  '{{apiKey}}'
);

<InstantSearch searchClient={searchClient} indexName="{{indexName}}">
  <SearchBox placeholder="{{searchPlaceholder}}" />
  {/* ... */}
</InstantSearch>
```

## Using the template

Create InstantSearch App reads your `.template.js` file and gets the specified tasks in the provided template.

Using the API:

```javascript
const app = createInstantSearchApp('my-app', {
  template: '/path/to/my-custom-template',
});

app.create();
```

Using the CLI:

```
create-instantsearch-app my-app --template /path/to/my-custom-template
```

## Examples

You can find all the officially supported templates in the [`src/templates/`](../src/templates) folder.

---

### Packages Create Instantsearch App Docs Deploy (`packages/create-instantsearch-app/docs/deploy.md`)

# Deploy an InstantSearch app

Create InstantSearch App generates applications that are ready to be deployed. They rely on bundlers and framework toolkits (Parcel, Create React App, Vue CLI, etc.).

Your app can be deployed in a single command, assuming you're located in its folder.

<details>
  <summary><strong>Contents</strong></summary>




- [CodeSandbox](#codesandbox)
- [Surge](#surge)
- [Vercel](#vercel)



</details>

## CodeSandbox

```
npx codesandbox .
```

[Learn more about CodeSandbox →](https://codesandbox.io)

## Surge

```
npx surge
```

[Learn more about Surge →](https://surge.sh)

## Vercel

```
npx vercel
```

[Learn more about Vercel →](https://vercel.com)

---

--- METRICS ---
- Files Extracted: 49
- Estimated Token Budget: ~33831 tokens
- Canonical Reference: https://codewiki.google/github.com/algolia/instantsearch