Get started with Vue InstantSearch

Use Vue InstantSearch to create a dynamic, filterable search UI.

Before you begin

This quickstart assumes basic Vue knowledge. It includes all the code, data, and credentials you need.

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

View demoView source code

1. Add starter code

   To generate some starter code, use the create-instantsearch-app tool. It provides the index data, all necessary code, and predefined credentials (application ID and API key).

   In a terminal, paste:

   npx create-instantsearch-app ais-ecommerce-demo-app --template "Vue InstantSearch"
   

   This command creates a folder structure on your machine:

   ais-ecommerce-demo-app/
   ├── node_modules/
   ├── src/
   ├──── App.vue
   ├──── main.js
   ├── package.json
   ├── README.md
   └── yarn.lock
   

2. Add the search UI

   Open src/App.vue and replace the whole file with the following:

   Vue

   <template>
     <ais-instant-search :search-client="searchClient" index-name="demo_ecommerce">
       <ais-search-box />
       <ais-hits>
         <template v-slot:item="{ item }">
           <h2>{{ item.name }}</h2>
         </template>
       </ais-hits>
     </ais-instant-search>
   </template>
   
   <script>
   import { liteClient as algoliasearch } from 'algoliasearch/lite';
   import 'instantsearch.css/themes/algolia-min.css';
   
   export default {
     data() {
       return {
         searchClient: algoliasearch(
           'B1G2GM9NG0',
           'aadef574be1f9252bb48d4ea09b5cfe5'
         ),
       };
     },
   };
   </script>
   
   <style>
   body {
     font-family: sans-serif;
     padding: 1em;
   }
   </style>
   

3. Run the project

   1. In your terminal, type:

      cd ais-ecommerce-demo-app
      npm start
      

   2. Open your browser and go to http://localhost:3000. The app displays the search box and results.

      
4. Add filters and settings

   Open src/App.vue and update it:

   Vue

   <template>
     <ais-instant-search index-name="demo_ecommerce" :search-client="searchClient">
       <div class="left-panel">
         <ais-clear-refinements />
         <h2>Brands</h2>
         <ais-refinement-list attribute="brand" searchable />
         <ais-configure :hitsPerPage="8" />
       </div>
       <div class="right-panel">
         <ais-search-box />
         <ais-hits>
           <template v-slot:item="{ item }">
             <h2>{{ item.name }}</h2>
           </template>
         </ais-hits>
         <ais-pagination />
       </div>
     </ais-instant-search>
   </template>
   

5. Create a two-column layout

   The widgets come with a predefined style but you can customize it.

   1. Update the content of the style tag with the following to apply a two-column layout:

      CSS

      body {
        font-family: sans-serif;
        padding: 1em;
      }
      
      .ais-Hits-list {
        margin-top: 0;
        margin-bottom: 1em;
      }
      
      .ais-InstantSearch {
        display: grid;
        grid-template-columns: 1fr 4fr;
        grid-gap: 1em;
      }
      

   2. In your browser, after a page refresh, the layout includes a set of brand filters.

      ![Search UI with a Brands filter in the quickstart app]](/images/instantsearch/vue/getting-started-2.png)

6. Format search results

   Open src/App.vue and replace the content of the ais-hits item slot with:

   Vue

   <template v-slot:item="{ item }">
     <h2>{{ item.name }}</h2>
     <img :src="item.image" align="left" :alt="item.name" />
     <div class="hit-name">
       <ais-highlight attribute="name" :hit="item"></ais-highlight>
     </div>
     <div class="hit-description">
       <ais-highlight attribute="description" :hit="item"></ais-highlight>
     </div>
     <div class="hit-price">{{ item.price }}</div>
   </template>
   

7. Refine the styling

   1. Update the content of the style tag with:

      CSS

      body {
        font-family: sans-serif;
        padding: 1em;
      }
      
      .ais-Hits-list {
        margin-top: 0;
        margin-bottom: 1em;
      }
      
      .ais-InstantSearch {
        display: grid;
        grid-template-columns: 1fr 4fr;
        grid-gap: 1em;
      }
      
      .ais-Hits-item img {
        margin-right: 1em;
      }
      .hit-name {
        margin-bottom: 0.5em;
      }
      .hit-description {
        color: #888;
        font-size: 0.8em;
        margin-bottom: 0.5em;
      }
      

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

      

The widgets

This quickstart uses several InstantSearch widgets:

• ais-instant-search is the root Vue InstantSearch component. You must wrap all other widgets inside this component.
• ais-search-box displays a search box for users to type queries into.
• ais-hits displays the results from Algolia, based on the query.
• ais-clear-refinements displays a button that clears the current refinements.
• ais-refinement-list displays a list of brands that users can use to filter the search.
• ais-configure passes search parameters. In this example, it sets hitsPerPage to 8.
• ais-pagination adds navigation controls to browse through pages of results.

Next steps

Instead of the credentials from create-instantsearch-app, use your own Algolia credentials.

You can send your own data or a sample dataset 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:

JavaScript

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

Initializing your app

If you’re using your app instead of create-instantsearch-app, initialize it by changing the contents of main.js to include the Vue InstantSearch library:

Vue 3

import { createApp } from "vue";
import App from "./App.vue";
import InstantSearch from "vue-instantsearch/vue3/es";

const app = createApp(App);
app.use(InstantSearch);
app.mount("#app");

See also

• What is InstantSearch?
• Send and update your data
• Send click and conversion events
• Customize an existing widget