Quick Start

This guide will help you create a working search interface in just a few minutes. We’ll build a simple product search with a search box, results display, and filtering.

Make sure you’ve installed InstantSearch before following this guide.

Choose Your Framework

Select the framework you’re using:

JavaScript
React
Vue

JavaScript Quick Start

Build a search UI with vanilla JavaScript.

Import the required packages

Create your JavaScript file and import InstantSearch:

import { liteClient as algoliasearch } from 'algoliasearch/lite';
import instantsearch from 'instantsearch.js';
import { searchBox, hits, refinementList, pagination, configure } from 'instantsearch.js/es/widgets';
import 'instantsearch.css/themes/satellite.css';

We’re using algoliasearch/lite which is a lighter version of the client optimized for search-only operations.

Initialize the search client

Create an Algolia search client with your credentials:

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

Replace YourApplicationID and YourSearchOnlyAPIKey with your actual Algolia credentials. Never use your Admin API Key in client-side code!

Create the InstantSearch instance

Initialize InstantSearch with your index name:

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

Add widgets to your search

Add UI widgets to display the search interface:

search.addWidgets([
  // Search box
  searchBox({
    container: '#searchbox',
    placeholder: 'Search for products...',
  }),

  // Search results
  hits({
    container: '#hits',
    templates: {
      item: (hit, { html, components }) => html`
        <article>
          <h2>${components.Highlight({ hit, attribute: 'name' })}</h2>
          <p>${components.Highlight({ hit, attribute: 'description' })}</p>
        </article>
      `,
    },
  }),

  // Configure search parameters
  configure({
    hitsPerPage: 12,
  }),

  // Category filter
  refinementList({
    container: '#categories',
    attribute: 'categories',
  }),

  // Pagination
  pagination({
    container: '#pagination',
  }),
]);

Start the search

Call start() to render the search UI:

search.start();

Add HTML containers

Create the HTML structure with container elements:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>InstantSearch.js App</title>
</head>
<body>
  <header>
    <h1>Search Products</h1>
    <div id="searchbox"></div>
  </header>

  <main>
    <aside>
      <h3>Categories</h3>
      <div id="categories"></div>
    </aside>

    <div>
      <div id="hits"></div>
      <div id="pagination"></div>
    </div>
  </main>

  <script type="module" src="/src/app.js"></script>
</body>
</html>

Complete Example

Here’s the complete JavaScript code:

import { liteClient as algoliasearch } from 'algoliasearch/lite';
import instantsearch from 'instantsearch.js';
import { 
  searchBox, 
  hits, 
  refinementList, 
  pagination, 
  configure 
} from 'instantsearch.js/es/widgets';
import 'instantsearch.css/themes/satellite.css';

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

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

search.addWidgets([
  searchBox({
    container: '#searchbox',
    placeholder: 'Search for products...',
  }),

  hits({
    container: '#hits',
    templates: {
      item: (hit, { html, components }) => html`
        <article>
          <h2>${components.Highlight({ hit, attribute: 'name' })}</h2>
          <p>${components.Highlight({ hit, attribute: 'description' })}</p>
        </article>
      `,
    },
  }),

  configure({
    hitsPerPage: 12,
  }),

  refinementList({
    container: '#categories',
    attribute: 'categories',
  }),

  pagination({
    container: '#pagination',
  }),
]);

search.start();

React Quick Start

Build a search UI with React components.

Import the required packages

Create your React component and import InstantSearch:

import { liteClient as algoliasearch } from 'algoliasearch/lite';
import React from 'react';
import {
  InstantSearch,
  SearchBox,
  Hits,
  RefinementList,
  Pagination,
  Highlight,
  Configure,
} from 'react-instantsearch';
import 'instantsearch.css/themes/satellite.css';

Initialize the search client

Create an Algolia search client with your credentials:

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

Replace YourApplicationID and YourSearchOnlyAPIKey with your actual Algolia credentials. Never use your Admin API Key in client-side code!

Create the App component

Build your search interface using React components:

export function App() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="your_index_name"
      insights={true}
    >
      <Configure hitsPerPage={12} />
      
      <header>
        <h1>Search Products</h1>
        <SearchBox placeholder="Search for products..." />
      </header>

      <main>
        <aside>
          <h3>Categories</h3>
          <RefinementList attribute="categories" />
        </aside>

        <div>
          <Hits hitComponent={Hit} />
          <Pagination />
        </div>
      </main>
    </InstantSearch>
  );
}

Create the Hit component

Define how individual search results should be displayed:

function Hit({ hit }) {
  return (
    <article>
      <h2>
        <Highlight attribute="name" hit={hit} />
      </h2>
      <p>
        <Highlight attribute="description" hit={hit} />
      </p>
    </article>
  );
}

Render your app

Mount your app to the DOM:

import { createRoot } from 'react-dom/client';

const root = createRoot(document.getElementById('root'));
root.render(<App />);

Complete Example

Here’s the complete React component:

import { liteClient as algoliasearch } from 'algoliasearch/lite';
import React from 'react';
import {
  InstantSearch,
  SearchBox,
  Hits,
  RefinementList,
  Pagination,
  Highlight,
  Configure,
} from 'react-instantsearch';
import { Hit } from 'instantsearch.js';
import 'instantsearch.css/themes/satellite.css';

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

export function App() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="your_index_name"
      insights={true}
    >
      <Configure hitsPerPage={12} />
      
      <header>
        <h1>Search Products</h1>
        <SearchBox placeholder="Search for products..." />
      </header>

      <main>
        <aside>
          <h3>Categories</h3>
          <RefinementList attribute="categories" />
        </aside>

        <div>
          <Hits hitComponent={HitComponent} />
          <Pagination />
        </div>
      </main>
    </InstantSearch>
  );
}

type HitType = Hit<{
  name: string;
  description: string;
}>;

function HitComponent({ hit }: { hit: HitType }) {
  return (
    <article>
      <h2>
        <Highlight attribute="name" hit={hit} />
      </h2>
      <p>
        <Highlight attribute="description" hit={hit} />
      </p>
    </article>
  );
}

TypeScript Support

React InstantSearch has full TypeScript support. Type your hit data for better autocomplete:

import { Hit } from 'instantsearch.js';

type ProductHit = Hit<{
  name: string;
  description: string;
  price: number;
  image: string;
  categories: string[];
}>;

function HitComponent({ hit }: { hit: ProductHit }) {
  // TypeScript knows about all your hit properties
  return (
    <article>
      <img src={hit.image} alt={hit.name} />
      <h2><Highlight attribute="name" hit={hit} /></h2>
      <p>{hit.price}</p>
    </article>
  );
}

Vue Quick Start

Build a search UI with Vue components.

In your main.js, register Vue InstantSearch:

import Vue from 'vue';
import InstantSearch from 'vue-instantsearch';
import App from './App.vue';

Vue.config.productionTip = false;
Vue.use(InstantSearch);

new Vue({
  render: (h) => h(App),
}).$mount('#app');

Create the search client

In your App.vue, import and create the search client:

<script>
import { liteClient as algoliasearch } from 'algoliasearch/lite';

export default {
  data() {
    return {
      searchClient: algoliasearch(
        'YourApplicationID',
        'YourSearchOnlyAPIKey'
      ),
    };
  },
};
</script>

Replace YourApplicationID and YourSearchOnlyAPIKey with your actual Algolia credentials. Never use your Admin API Key in client-side code!

Build the template

Use InstantSearch Vue components in your template:

<template>
  <div>
    <ais-instant-search
      :search-client="searchClient"
      index-name="your_index_name"
      :insights="true"
    >
      <ais-configure :hits-per-page.camel="12" />
      
      <header>
        <h1>Search Products</h1>
        <ais-search-box placeholder="Search for products..." />
      </header>

      <main>
        <aside>
          <h3>Categories</h3>
          <ais-refinement-list attribute="categories" />
        </aside>

        <div>
          <ais-hits>
            <template slot="item" slot-scope="{ item }">
              <article>
                <h2>
                  <ais-highlight :hit="item" attribute="name" />
                </h2>
                <p>
                  <ais-highlight :hit="item" attribute="description" />
                </p>
              </article>
            </template>
          </ais-hits>

          <ais-pagination />
        </div>
      </main>
    </ais-instant-search>
  </div>
</template>

Add styles

Import the InstantSearch CSS theme:

<style>
@import 'instantsearch.css/themes/satellite.css';

/* Your custom styles */
main {
  display: flex;
  gap: 2rem;
}

aside {
  flex: 1;
}

aside + div {
  flex: 3;
}
</style>

Complete Example

Here’s the complete Vue component:

<template>
  <div>
    <ais-instant-search
      :search-client="searchClient"
      index-name="your_index_name"
      :insights="true"
    >
      <ais-configure :hits-per-page.camel="12" />
      
      <header>
        <h1>Search Products</h1>
        <ais-search-box placeholder="Search for products..." />
      </header>

      <main>
        <aside>
          <h3>Categories</h3>
          <ais-refinement-list attribute="categories" />
        </aside>

        <div>
          <ais-hits>
            <template slot="item" slot-scope="{ item }">
              <article>
                <h2>
                  <ais-highlight :hit="item" attribute="name" />
                </h2>
                <p>
                  <ais-highlight :hit="item" attribute="description" />
                </p>
              </article>
            </template>
          </ais-hits>

          <ais-pagination />
        </div>
      </main>
    </ais-instant-search>
  </div>
</template>

<script>
import { liteClient as algoliasearch } from 'algoliasearch/lite';

export default {
  data() {
    return {
      searchClient: algoliasearch(
        'YourApplicationID',
        'YourSearchOnlyAPIKey'
      ),
    };
  },
};
</script>

<style>
@import 'instantsearch.css/themes/satellite.css';

main {
  display: flex;
  gap: 2rem;
  max-width: 1200px;
  margin: 0 auto;
  padding: 2rem;
}

aside {
  flex: 1;
}

aside + div {
  flex: 3;
}

header {
  padding: 2rem;
  background: linear-gradient(to right, #4dba87, #2f9088);
  color: white;
}

header h1 {
  margin: 0 0 1rem 0;
}
</style>

Vue 3 Support

For Vue 3, the component usage is similar but you don’t need to call Vue.use():

// main.js for Vue 3
import { createApp } from 'vue';
import InstantSearch from 'vue-instantsearch/vue3/es';
import App from './App.vue';

createApp(App)
  .use(InstantSearch)
  .mount('#app');

Testing Your Search

Once you’ve implemented the code:

Start your development server

Run your development server to see the search UI:

npm run dev
# or
yarn dev
# or
pnpm dev

Verify the search works

Open your browser and try:

Typing in the search box - results should update instantly
Clicking category filters - results should filter accordingly
Using pagination - navigate through result pages

Check the browser console

Open your browser’s developer console to check for any errors or warnings.

What’s Happening?

Let’s break down the key parts:

Search Client - Connects to your Algolia application using the lite client (optimized for search)
InstantSearch Instance - The main container that manages the search state
Widgets/Components - UI elements that render and interact with the search:
- SearchBox - Input field for search queries
- Hits - Displays search results
- RefinementList - Faceted filter for attributes
- Pagination - Navigate through pages
- Configure - Set search parameters
Highlight - Highlights matching terms in results

Customization

Now that you have a basic search working, you can customize it:

Add More Widgets

Explore the widget library to add features like:

Range Sliders - Filter by price or numeric ranges
Sort By - Let users change result ordering
Current Refinements - Show active filters with clear buttons
Stats - Display result count and search time
Clear Refinements - Reset all filters at once

Style Your Search

Customize the appearance:

Override CSS classes (all widgets use BEM naming)
Create custom templates for results
Use your own CSS framework
Build custom widgets

Configure Search Behavior

Adjust how search works:

Set ranking rules
Configure typo tolerance
Add custom ranking
Set searchable attributes

Next Steps

Now that you have a working search, explore these topics:

Widget Showcase

Browse all available widgets and their options

Customization Guide

Learn how to style and customize your search UI

Server-Side Rendering

Implement SSR for better SEO and performance

Routing

Sync search state with the URL for shareable links

Using the demo API keys? They’re limited to 10,000 records and read-only access. For production apps, create your own Algolia account and use your own credentials.

Troubleshooting

Search Results Not Appearing

Verify your Application ID and API Key are correct
Check that your index name matches exactly
Ensure your index has data
Check the browser console for errors

Widgets Not Rendering

Verify HTML containers exist (JavaScript version)
Check that you called search.start() (JavaScript version)
Ensure the InstantSearch component wraps all widgets (React/Vue)

TypeScript Errors

Install the correct type packages for your Algolia client version
Import the Hit type from instantsearch.js
Type your hit data properly

Need Help?

Check out these resources:

Getting Started

Core Concepts

Vanilla JavaScript

React

Vue

Advanced Guides

Choose Your Framework

JavaScript Quick Start

Complete Example

React Quick Start

Complete Example

TypeScript Support

Vue Quick Start

Complete Example

Vue 3 Support

Testing Your Search

What’s Happening?

Customization

Add More Widgets

Style Your Search

Configure Search Behavior

Next Steps

Widget Showcase

Customization Guide

Server-Side Rendering

Routing

Troubleshooting

Search Results Not Appearing

Widgets Not Rendering

TypeScript Errors

Need Help?

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Vanilla JavaScript

React

Vue

Advanced Guides

​Choose Your Framework

​JavaScript Quick Start

​Complete Example

​React Quick Start

​Complete Example

​TypeScript Support

​Vue Quick Start

​Complete Example

​Vue 3 Support

​Testing Your Search

​What’s Happening?

​Customization

​Add More Widgets

​Style Your Search

​Configure Search Behavior

​Next Steps

Widget Showcase

Customization Guide

Server-Side Rendering

Routing

​Troubleshooting

​Search Results Not Appearing

​Widgets Not Rendering

​TypeScript Errors

​Need Help?

Build docs developers (and LLMs) love

Choose Your Framework

JavaScript Quick Start

Complete Example

React Quick Start

Complete Example

TypeScript Support

Vue Quick Start

Complete Example

Vue 3 Support

Testing Your Search

What’s Happening?

Customization

Add More Widgets

Style Your Search

Configure Search Behavior

Next Steps

Troubleshooting

Search Results Not Appearing

Widgets Not Rendering

TypeScript Errors

Need Help?