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

# Get started with Autocomplete

> Get started with Autocomplete by building an Algolia search experience.

<Tip>
  Autocomplete is also available as an experimental widget in InstantSearch,
  making it easier to integrate into your search experience.
  For more information,
  see the API reference for [InstantSearch.js](/doc/api-reference/widgets/autocomplete/js) or
  [React InstantSearch](/doc/api-reference/widgets/autocomplete/react).
</Tip>

This documentation offers a few ways to learn about the Autocomplete library:

* Read the [Core concepts](/doc/ui-libraries/autocomplete/core-concepts/basic-configuration-options) to learn more about underlying principles, like [Sources](/doc/ui-libraries/autocomplete/core-concepts/sources) and [State](/doc/ui-libraries/autocomplete/core-concepts/state).
* Follow the [Guides](/doc/ui-libraries/autocomplete/guides/adding-suggested-searches) to understand how to build common UX patterns.
* Refer to the [API reference](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js) for a comprehensive list of parameters and options.
* Try out the [Playground](https://codesandbox.io/s/github/algolia/autocomplete/tree/next/examples/playground?file=/app.tsx) where you can fork a basic implementation and play around.

Keep reading to see how to install Autocomplete and build a basic implementation with Algolia.

## Installation

The recommended way to get started is with the [`autocomplete-js`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js) package. It includes everything you need to render a JavaScript autocomplete experience.

Otherwise, you can install the [`autocomplete-core`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-core) package if you want to [build a renderer](/doc/ui-libraries/autocomplete/guides/creating-a-renderer) from scratch.

All Autocomplete packages are available on the [npm](https://www.npmjs.com/) registry.

<CodeGroup>
  ```sh npm theme={"system"}
  npm install algoliasearch @algolia/autocomplete-js
  ```

  ```sh yarn theme={"system"}
  yarn add algoliasearch @algolia/autocomplete-js
  ```
</CodeGroup>

If you don't want to use a package manager, you can use a standalone endpoint:

```html HTML icon=code-xml theme={"system"}
<script
  src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-js@1.19.9/dist/umd/index.production.js"
  integrity="sha256-wpkAnzdLcIepcHpyULu6SUAwGne9BupLbkv+uv/SUeI="
  crossorigin="anonymous"
>
</script>
<script>
  const { autocomplete } = window["@algolia/autocomplete-js"];
</script>
```

Algolia recommends using [jsDelivr](https://www.jsdelivr.com) but [`autocomplete-js`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js) is also available through [unpkg](https://unpkg.com/@algolia/autocomplete-js).

### Install the Autocomplete classic theme

The Autocomplete library provides the [`autocomplete-theme-classic`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-theme-classic) package so that you can have sleek styling out of the box.

If you want a custom theme, use this classic theme and customize it with [CSS variables](/doc/ui-libraries/autocomplete/api-reference/autocomplete-theme-classic). You can also create an entirely new theme using the classic theme as a starting point.

This example uses the out of the box classic theme. You can import it like any other Autocomplete package.

<CodeGroup>
  ```sh npm theme={"system"}
  npm install @algolia/autocomplete-theme-classic
  ```

  ```sh yarn theme={"system"}
  yarn add @algolia/autocomplete-theme-classic
  ```
</CodeGroup>

Then import it in your project:

```js JavaScript icon=code theme={"system"}
import "@algolia/autocomplete-theme-classic";
```

If you don't use a package manager, you can link the style sheet in your HTML:

```html HTML icon=code-xml theme={"system"}
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-theme-classic@1.19.9/dist/theme.min.css"
  integrity="sha256-6VZg2e7ColRlFrMMzaMK5UHpeEPD2o4pJ4kBBPvt19E="
  crossorigin="anonymous"
/>
```

<Note>
  Algolia doesn't provide support regarding third party services like jsDelivr or other CDNs.
</Note>

## Define where to put your autocomplete

To get started, you need a container for your autocomplete to go in. If you don't have one already, you can insert one into your markup:

```html HTML icon=code-xml theme={"system"}
<div id="autocomplete"></div>
```

Then, insert your autocomplete into it by calling the [`autocomplete`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete) function and providing the [`container`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete#param-container). It can be a [CSS selector](https://developer.mozilla.org/docs/Web/CSS/CSS_Selectors) or an [Element](https://developer.mozilla.org/docs/Web/API/HTMLElement).

Make sure to provide a container (for example, a `div`), not an `input`. Autocomplete generates a fully accessible search box for you.

```js JavaScript icon=code theme={"system"}
import { autocomplete } from "@algolia/autocomplete-js";

import "@algolia/autocomplete-theme-classic";

autocomplete({
  container: "#autocomplete",
  placeholder: "Search for products",
  getSources() {
    return [];
  },
});
```

You may have noticed two options: [`placeholder`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete#param-placeholder) and [`getSources`](/doc/ui-libraries/autocomplete/core-concepts/sources#param-get-sources).
The [`placeholder`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete#param-placeholder) option defines the text to show until users start typing in the input.

Autocomplete is now plugged in. But you won't see anything appear until you define your [sources](/doc/ui-libraries/autocomplete/core-concepts/sources).

## Define what items to display

[Sources](/doc/ui-libraries/autocomplete/core-concepts/sources) define where to retrieve the items to display in your Autocomplete drop-down menu.
You define your sources in the [`getSources`](/doc/ui-libraries/autocomplete/core-concepts/sources#param-get-sources) function by returning an array of [source objects](/doc/ui-libraries/autocomplete/core-concepts/sources#param-source-id).

Each source object needs to include a [`sourceId`](/doc/ui-libraries/autocomplete/core-concepts/sources#param-source-id) and a [`getItems`](/doc/ui-libraries/autocomplete/core-concepts/sources#param-get-items) function that returns the items to display. Sources can be static or dynamic.

This example uses an [Algolia index](https://support.algolia.com/hc/en-us/articles/4406981910289-What-is-an-index-) of [ecommerce products](https://github.com/algolia/datasets/tree/master/ecommerce) as a source. The [`autocomplete-js`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js) package provides a built-in [`getAlgoliaResults`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/getAlgoliaResults) function for just this purpose.

```js JavaScript icon=code theme={"system"}
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { autocomplete, getAlgoliaResults } from "@algolia/autocomplete-js";

import "@algolia/autocomplete-theme-classic";

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

autocomplete({
  container: "#autocomplete",
  placeholder: "Search for products",
  getSources({ query }) {
    return [
      {
        sourceId: "products",
        getItems() {
          return getAlgoliaResults({
            searchClient,
            queries: [
              {
                indexName: "instant_search",
                params: {
                  query,
                  hitsPerPage: 5,
                },
              },
            ],
          });
        },
        // ...
      },
    ];
  },
});
```

The [`getAlgoliaResults`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/getAlgoliaResults) function requires an [Algolia search client](/doc/libraries/sdk/install)
initialized with an [Algolia application ID and API key](/doc/guides/sending-and-managing-data/send-and-update-your-data/how-to/importing-with-the-api#required-credentials).
It lets you search into your Algolia index using an array of `queries`, which defines one or more queries to send to the index.

This example makes just one query to the "autocomplete" index using the `query` from [`getSources`](/doc/ui-libraries/autocomplete/core-concepts/sources#param-get-sources). For now, it passes one additional parameter, [`hitsPerPage`](/doc/api-reference/api-parameters/hitsPerPage) to define how many items to display, but you could pass any other [Algolia query parameters](/doc/api-reference/api-parameters).

Although you've now declared what items to display using [`getSources`](/doc/ui-libraries/autocomplete/core-concepts/sources#param-get-sources), you still won't see anything until you've defined how to display the items you've retrieved.

## Define how to display items

[Sources](/doc/ui-libraries/autocomplete/core-concepts/sources) also define how to display items in your Autocomplete using [`templates`](/doc/ui-libraries/autocomplete/core-concepts/templates). Templates can return a string or anything that's a valid Virtual DOM element. The example creates a [Preact](https://preactjs.com/) component called `ProductItem` to use as the template for each item.

The CSS classes correspond to the [classic theme](/doc/ui-libraries/autocomplete/api-reference/autocomplete-theme-classic) imported earlier.

<CodeGroup>
  ```js JavaScript theme={"system"}
  import { autocomplete, getAlgoliaResults } from "@algolia/autocomplete-js";
  import algoliasearch from "algoliasearch";

  import "@algolia/autocomplete-theme-classic";

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

  autocomplete({
    container: "#autocomplete",
    placeholder: "Search for products",
    insights: true,
    getSources({ query }) {
      return [
        {
          sourceId: "products",
          getItems() {
            return getAlgoliaResults({
              searchClient,
              queries: [
                {
                  indexName: "instant_search",
                  params: {
                    query,
                    hitsPerPage: 5,
                    attributesToSnippet: ["name:10", "description:35"],
                    snippetEllipsisText: "…",
                  },
                },
              ],
            });
          },
          templates: {
            item({ item, components, html }) {
              return html`<div class="aa-ItemWrapper">
                <div class="aa-ItemContent">
                  <div class="aa-ItemIcon aa-ItemIcon--alignTop">
                    <img
                      src="${item.image}"
                      alt="${item.name}"
                      width="40"
                      height="40"
                    />
                  </div>
                  <div class="aa-ItemContentBody">
                    <div class="aa-ItemContentTitle">
                      ${components.Highlight({
                        hit: item,
                        attribute: "name",
                      })}
                    </div>
                    <div class="aa-ItemContentDescription">
                      ${components.Snippet({
                        hit: item,
                        attribute: "description",
                      })}
                    </div>
                  </div>
                  <div class="aa-ItemActions">
                    <button
                      class="aa-ItemActionButton aa-DesktopOnly aa-ActiveOnly"
                      type="button"
                      title="Select"
                    >
                      <svg
                        viewBox="0 0 24 24"
                        width="20"
                        height="20"
                        fill="currentColor"
                      >
                        <path
                          d="M18.984 6.984h2.016v6h-15.188l3.609 3.609-1.406 1.406-6-6 6-6 1.406 1.406-3.609 3.609h13.172v-4.031z"
                        />
                      </svg>
                    </button>
                    <button
                      class="aa-ItemActionButton"
                      type="button"
                      title="Add to cart"
                    >
                      <svg
                        viewBox="0 0 24 24"
                        width="18"
                        height="18"
                        fill="currentColor"
                      >
                        <path
                          d="M19 5h-14l1.5-2h11zM21.794 5.392l-2.994-3.992c-0.196-0.261-0.494-0.399-0.8-0.4h-12c-0.326 0-0.616 0.156-0.8 0.4l-2.994 3.992c-0.043 0.056-0.081 0.117-0.111 0.182-0.065 0.137-0.096 0.283-0.095 0.426v14c0 0.828 0.337 1.58 0.879 2.121s1.293 0.879 2.121 0.879h14c0.828 0 1.58-0.337 2.121-0.879s0.879-1.293 0.879-2.121v-14c0-0.219-0.071-0.422-0.189-0.585-0.004-0.005-0.007-0.010-0.011-0.015zM4 7h16v13c0 0.276-0.111 0.525-0.293 0.707s-0.431 0.293-0.707 0.293h-14c-0.276 0-0.525-0.111-0.707-0.293s-0.293-0.431-0.293-0.707zM15 10c0 0.829-0.335 1.577-0.879 2.121s-1.292 0.879-2.121 0.879-1.577-0.335-2.121-0.879-0.879-1.292-0.879-2.121c0-0.552-0.448-1-1-1s-1 0.448-1 1c0 1.38 0.561 2.632 1.464 3.536s2.156 1.464 3.536 1.464 2.632-0.561 3.536-1.464 1.464-2.156 1.464-3.536c0-0.552-0.448-1-1-1s-1 0.448-1 1z"
                        />
                      </svg>
                    </button>
                  </div>
                </div>
              </div>`;
            },
          },
        },
      ];
    },
  });
  ```

  ```jsx JSX theme={"system"}
  /** @jsx h */
  import { autocomplete, getAlgoliaResults } from "@algolia/autocomplete-js";
  import algoliasearch from "algoliasearch";
  import { h, Fragment } from "preact";

  import "@algolia/autocomplete-theme-classic";

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

  autocomplete({
    container: "#autocomplete",
    placeholder: "Search for products",
    insights: true,
    getSources({ query }) {
      return [
        {
          sourceId: "products",
          getItems() {
            return getAlgoliaResults({
              searchClient,
              queries: [
                {
                  indexName: "instant_search",
                  params: {
                    query,
                    hitsPerPage: 5,
                    attributesToSnippet: ["name:10", "description:35"],
                    snippetEllipsisText: "…",
                  },
                },
              ],
            });
          },
          templates: {
            item({ item, components }) {
              return <ProductItem hit={item} components={components} />;
            },
          },
        },
      ];
    },
  });

  function ProductItem({ hit, components }) {
    return (
      <div className="aa-ItemWrapper">
        <div className="aa-ItemContent">
          <div className="aa-ItemIcon aa-ItemIcon--alignTop">
            <img src={hit.image} alt={hit.name} width="40" height="40" />
          </div>
          <div className="aa-ItemContentBody">
            <div className="aa-ItemContentTitle">
              <components.Highlight hit={hit} attribute="name" />
            </div>
            <div className="aa-ItemContentDescription">
              <components.Snippet hit={hit} attribute="description" />
            </div>
          </div>
          <div className="aa-ItemActions">
            <button
              className="aa-ItemActionButton aa-DesktopOnly aa-ActiveOnly"
              type="button"
              title="Select"
            >
              <svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor">
                <path d="M18.984 6.984h2.016v6h-15.188l3.609 3.609-1.406 1.406-6-6 6-6 1.406 1.406-3.609 3.609h13.172v-4.031z" />
              </svg>
            </button>
            <button
              className="aa-ItemActionButton"
              type="button"
              title="Add to cart"
            >
              <svg viewBox="0 0 24 24" width="18" height="18" fill="currentColor">
                <path d="M19 5h-14l1.5-2h11zM21.794 5.392l-2.994-3.992c-0.196-0.261-0.494-0.399-0.8-0.4h-12c-0.326 0-0.616 0.156-0.8 0.4l-2.994 3.992c-0.043 0.056-0.081 0.117-0.111 0.182-0.065 0.137-0.096 0.283-0.095 0.426v14c0 0.828 0.337 1.58 0.879 2.121s1.293 0.879 2.121 0.879h14c0.828 0 1.58-0.337 2.121-0.879s0.879-1.293 0.879-2.121v-14c0-0.219-0.071-0.422-0.189-0.585-0.004-0.005-0.007-0.010-0.011-0.015zM4 7h16v13c0 0.276-0.111 0.525-0.293 0.707s-0.431 0.293-0.707 0.293h-14c-0.276 0-0.525-0.111-0.707-0.293s-0.293-0.431-0.293-0.707zM15 10c0 0.829-0.335 1.577-0.879 2.121s-1.292 0.879-2.121 0.879-1.577-0.335-2.121-0.879-0.879-1.292-0.879-2.121c0-0.552-0.448-1-1-1s-1 0.448-1 1c0 1.38 0.561 2.632 1.464 3.536s2.156 1.464 3.536 1.464 2.632-0.561 3.536-1.464 1.464-2.156 1.464-3.536c0-0.552-0.448-1-1-1s-1 0.448-1 1z" />
              </svg>
            </button>
          </div>
        </div>
      </div>
    );
  }
  ```
</CodeGroup>

The `ProductItem` component uses the `Snippet` component to only display part of the item's name and description,
if they go beyond a certain length.
Each attribute's allowed length and the characters to show when truncated are defined in the [`attributesToSnippet`](/doc/api-reference/api-parameters/attributesToSnippet) and [`snippetEllipsisText`](/doc/api-reference/api-parameters/snippetEllipsisText) [Algolia query parameters](/doc/api-reference/api-parameters) in `params`.

This is what the truncated JSON record looks like:

```json JSON icon=braces theme={"system"}
{
  "name": "Apple - MacBook Air® (Latest Model) - 13.3\" Display - Intel Core i5 - 4GB Memory - 128GB Flash Storage - Silver",
  "description": "MacBook Air features fifth-generation Intel Core processors with stunning graphics, all-day battery life*, ultrafast flash storage, and great built-in apps. It's thin, light and durable enough to take everywhere you go &#8212; and powerful enough to do everything once you get there.",
  "image": "https://cdn-demo.algolia.com/bestbuy/1581921_sb.jpg",
  "url": "http://www.bestbuy.com/site/apple-macbook-air-latest-model-13-3-display-intel-core-i5-4gb-memory-128gb-flash-storage-silver/1581921.p?id=1219056464137&skuId=1581921&cmp=RMX&ky=1uWSHMdQqBeVJB9cXgEke60s5EjfS6M1W",
  "objectID": "1581921"
}
```

Check out how the template displays items by searching in the input below:

## Keep the panel open during development

When you're building, styling, or debugging your autocomplete experience,
you might want to inspect it in your web developer tools.
Set the [`debug`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete#param-debug) option to `true` to keep the panel open when inspecting it.

<Note>
  Only use the [`debug`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete#param-debug) option during development.
</Note>

## Send click and conversion events

To send [click and conversion events](/doc/ui-libraries/autocomplete/guides/sending-algolia-insights-events) when users interact with your autocomplete experience,
set the [`insights`](/doc/ui-libraries/autocomplete/api-reference/autocomplete-js/autocomplete#param-insights) option to `true`.

```js JavaScript icon=code theme={"system"}
import { autocomplete } from "@algolia/autocomplete-js";

autocomplete({
  // ...
  insights: true,
});
```

## Browser support

Algolia supports the last two versions of the major browsers: Chrome, Edge, Firefox, Safari.

## Going further

This is all you need for a basic implementation.
To go further,
you can use the [`getItemUrl`](/doc/ui-libraries/autocomplete/core-concepts/sources#param-get-item-url)
to add [keyboard accessibility](/doc/ui-libraries/autocomplete/core-concepts/keyboard-navigation) features.
It lets users open items directly from the autocomplete menu.

```js JavaScript icon=code theme={"system"}
import { autocomplete, getAlgoliaResults } from "@algolia/autocomplete-js";
import algoliasearch from "algoliasearch";

import "@algolia/autocomplete-theme-classic";

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

autocomplete({
  container: "#autocomplete",
  placeholder: "Search for products",
  getSources({ query }) {
    return [
      {
        sourceId: "products",
        getItems() {
          // ...
        },
        templates: {
          // ...
        },
        getItemUrl({ item }) {
          return item.url;
        },
      },
    ];
  },
});
```

This outlines a basic autocomplete implementation.
There's a lot more you can do like:

* Define [templates for headers, footers](/doc/ui-libraries/autocomplete/core-concepts/templates#render-a-header-and-footer), or when there's [no results](/doc/ui-libraries/autocomplete/core-concepts/templates#render-a-no-results-state)
* [Add multiple sources](/doc/ui-libraries/autocomplete/guides/including-multiple-result-types), including [suggested searches](/doc/ui-libraries/autocomplete/guides/adding-suggested-searches) and [recent searches](/doc/ui-libraries/autocomplete/guides/adding-recent-searches)
* [Send Algolia Insights events](/doc/ui-libraries/autocomplete/guides/sending-algolia-insights-events) when a user clicks on an item or adds it to their cart

To learn about customization options, read the [core concepts](/doc/ui-libraries/autocomplete/core-concepts/basic-configuration-options) or follow one of the [Guides](/doc/ui-libraries/autocomplete/guides/adding-suggested-searches).