> ## Documentation Index
> Fetch the complete documentation index at: https://www.algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with InstantSearch.js

> Use InstantSearch.js to create a dynamic, filterable search UI.

## Before you begin

This quickstart requires:

* Basic JavaScript knowledge.
* **[Node.js](https://nodejs.org/en/download)** version 16 or later with **npm** version 5.2 or later.

## Quickstart

In this quickstart, you'll add an Algolia search interface to some starter code.
The code:

* Displays and formats a search box and results
* Uses InstantSearch's pre-built UI components (widgets) to filter results

> [card] [Open CodeSandbox](https://codesandbox.io/s/github/algolia/instantsearch/tree/master/examples/js/getting-started)
>
> Run and edit the InstantSearch.js quickstart example in CodeSandbox.

> [card] [Explore source code](https://github.com/algolia/instantsearch/tree/master/examples/js/getting-started)
>
> Browse the source for the InstantSearch.js quickstart example on GitHub.

**1. Add starter code**

To generate some starter code, use the `create-instantsearch-app` tool.
It provides the index (An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.) data, all necessary code, and predefined credentials (application ID (A unique alphanumeric string that identifies an Algolia application.) and API key (An alphanumeric string that controls access to the Algolia APIs. It defines what actions are allowed, such as searching an index or adding new records.)).

In a terminal, paste:

```sh Command line icon=square-terminal theme={"system"}
npx create-instantsearch-app@latest ais-ecommerce-demo-app \
  --template "InstantSearch.js" \
  --app-id "B1G2GM9NG0" \
  --api-key "aadef574be1f9252bb48d4ea09b5cfe5" \
  --index-name demo_ecommerce \
  --attributes-to-display name \
  --attributes-for-faceting ''
```

This command creates a folder structure on your machine:

```txt theme={"system"}
ais-ecommerce-demo-app/
├── node_modules
├── src
│   ├── app.css
│   └── app.js
├── .editorconfig
├── .eslintignore
├── .eslintrc.js
├── .gitignore
├── .prettierrc
├── favicon.png
├── index.html
├── package.json
└── README.md
```

**2. Add the search UI**

1. In `index.html`, remove the `header`, and replace `<div class="container">` with:

   ```html HTML icon=code-xml theme={"system"}
   <div class="ais-InstantSearch">
     <h1>InstantSearch.js e-commerce demo</h1>

     <div class="right-panel">
       <div id="searchbox"></div>
       <div id="hits"></div>
       <div id="pagination"></div>
     </div>
   </div>
   ```

2. Open `src/app.css` and replace its content with:

```css CSS icon=paintbrush theme={"system"}
        body {
          font-family: sans-serif;
          padding: 1em;
        }
        .ais-SearchBox {
          margin: 1em 0;
        }
```

**3. Run the app**

1. In your terminal, type:

   ```sh Command line icon=square-terminal theme={"system"}
   cd ais-ecommerce-demo-app
   npm start
   ```

2. Open your browser and go to [http://localhost:3000](https://localhost:3000).
   The app displays the search box, results, and pagination components.

   ![Search box with results and pagination in the quickstart app](https://mintcdn.com/algolia/1WCtS02LoYjihIhK/images/instantsearch/js/getting-started-1.png?fit=max\&auto=format\&n=1WCtS02LoYjihIhK\&q=85\&s=b3a130bf601d55e69f790d152024aad8)

**4. Add filters and settings**

1. Open `index.html` and update it to:

   ```html HTML icon=code-xml theme={"system"}
   <div class="ais-InstantSearch">
     <h1>InstantSearch.js e-commerce demo</h1>

     <div class="left-panel">
       <div id="clear-refinements"></div>

       <h2>Brands</h2>
       <div id="brand-list"></div>
     </div>

     <div class="right-panel">
       <div id="searchbox"></div>
       <div id="hits"></div>
       <div id="pagination"></div>
     </div>
   </div>
   ```

2. Open `src/app.js`, and add widgets to these placeholders:

   ```js JavaScript icon=code theme={"system"}
   // Before `search.start()`
   search.addWidgets([
     instantsearch.widgets.clearRefinements({
       container: "#clear-refinements",
     }),

     instantsearch.widgets.refinementList({
       container: "#brand-list",
       attribute: "brand",
     }),

     instantsearch.widgets.configure({
       hitsPerPage: 8,
     }),
   ]);
   ```

**5. Create a two-column layout**

The widgets come with a [predefined style](https://www.algolia.com/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js.md#style-your-widgets) but you can customize it.

1. Open `src/app.css` and update it to the following to apply a two-column layout:

```css CSS icon=paintbrush theme={"system"}
          body {
            font-family: sans-serif;
            padding: 1em;
          }
          .ais-SearchBox {
            margin: 1em 0;
          }
          .ais-Pagination {
            margin-top: 1em;
          }
          .left-panel {
            float: left;
            margin-top: 1em;
            width: 250px;
          }
          .right-panel {
            margin-left: 260px;
          }
```

1. In your browser, after a page refresh, the layout includes a **Brands** filter (A filter is a condition that limits which records Algolia returns. Filters often use one or more facet-value pairs, such as brand:Apple AND color:red. You can also filter by numeric values, dates, tags, booleans, or geographic constraints.).

   ![Search UI with a Brands filter in the quickstart app](https://mintcdn.com/algolia/1WCtS02LoYjihIhK/images/instantsearch/js/getting-started-2.png?fit=max\&auto=format\&n=1WCtS02LoYjihIhK\&q=85\&s=a945c7305924ba7b702f2960103be127)

**6. Format search results**

Open the `src/app.js` and replace the content of the `hits` widget with:

```js JavaScript icon=code theme={"system"}
search.addWidgets([
  instantsearch.widgets.hits({
    container: "#hits",
    templates: {
      item: (hit, { html, components }) => html`
        <div>
          <img src="${hit.image}" align="left" alt="${hit.name}" />
          <div class="hit-name">
            ${components.Highlight({ hit, attribute: "name" })}
          </div>
          <div class="hit-description">
            ${components.Highlight({ hit, attribute: "description" })}
          </div>
          <div class="hit-price">$${hit.price}</div>
        </div>
      `,
    },
  }),
]);
```

**7. Refine the styling**

1. Open `src/app.css` and replace its content with:

```css CSS icon=paintbrush theme={"system"}
        body {
          font-family: sans-serif;
          padding: 1em;
        }
        .ais-SearchBox {
          margin: 1em 0;
        }
        .ais-Pagination {
          margin-top: 1em;
        }
        .left-panel {
          float: left;
          margin-top: 1em;
          width: 250px;
        }
        .right-panel {
          margin-left: 260px;
        }
        .ais-InstantSearch {
          max-width: 960px;
          margin: 0 auto;
        }
        .ais-Hits-list {
          display: grid;
          grid-template-columns: repeat(2, 1fr);
          grid-gap: 1em;
        }
        .ais-Hits-item img {
          margin-right: 1em;
        }
        .hit-name {
          margin-bottom: 0.5em;
        }
        .hit-description {
          color: #888;
          font-size: 14px;
          margin-bottom: 0.5em;
        }
```

In your browser, after a page refresh, you'll see product images.

![Search UI with product images in the quickstart app](https://mintcdn.com/algolia/1WCtS02LoYjihIhK/images/instantsearch/js/getting-started-3.png?fit=max\&auto=format\&n=1WCtS02LoYjihIhK\&q=85\&s=47192e749d189e8989f2904caa361c04)

## The widgets

This quickstart uses several InstantSearch widgets:

* [`instantsearch`](https://www.algolia.com/doc/api-reference/widgets/instantsearch/js) is the root InstantSearch.js component. You must wrap all other widgets inside this component.
* [`searchBox`](https://www.algolia.com/doc/api-reference/widgets/search-box/js) displays a search box for users to type queries into.
* [`hits`](https://www.algolia.com/doc/api-reference/widgets/hits/js) displays the results from Algolia, based on the search query (The text users enter into a search box. In the Search API, this corresponds to the query parameter. A search query is often used with filters, facets, and other parameters, but these aren't part of the query text itself.).
* [`pagination`](https://www.algolia.com/doc/api-reference/widgets/pagination/js) adds navigation controls to browse through pages of results.
* [`clearRefinements`](https://www.algolia.com/doc/api-reference/widgets/clear-refinements/js) displays a button that clears the current refinements.
* [`refinementList`](https://www.algolia.com/doc/api-reference/widgets/refinement-list/js) displays a list of brands that users can use to filter the search.
* [`configure`](https://www.algolia.com/doc/api-reference/widgets/configure/js) passes [search parameters](https://www.algolia.com/doc/api-reference/search-api-parameters.md). In this quickstart, it sets `hitsPerPage` to 8.

## Next steps

Instead of the credentials from `create-instantsearch-app`,
use your own Algolia [credentials](https://www.algolia.com/users/sign_up).

You can send your own data or [a sample dataset](https://github.com/algolia/datasets/blob/master/ecommerce/records.json) to Algolia using the JavaScript API client that comes preinstalled with `create-instantsearch-app`.

Then, configure the index with the JavaScript API client.
For example, to configure the sample dataset,
use the following code:

```js JavaScript icon="code" theme={"system"}
index
  .setSettings({
    searchableAttributes: [
      "brand",
      "name",
      "categories",
      "unordered(description)",
    ],
    customRanking: ["desc(popularity)"],
    attributesForFaceting: ["searchable(brand)", "type", "categories", "price"],
  })
  .then(() => {
    // done
  });
```

## See also

* [What is InstantSearch?](https://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/js.md)
* [Send and update your data](https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data)
* [InstantSearch widgets](https://www.algolia.com/doc/api-reference/widgets/js.md)
* [Customize an existing widget](https://www.algolia.com/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js.md)
* [Send click and conversion events](https://www.algolia.com/doc/guides/building-search-ui/events/js.md)
