Guides / Building Search UI

Feb 18, 2025

Getting started with Vue InstantSearch

Before you begin

This tutorial assumes you have Vue knowledge and have installed Vue InstantSearch.

Tutorial

In this tutorial, you’ll add an Algolia search interface to some starter code.

Add starter code

To generate some starter code, use the create-instantsearch-app installed with Vue InstantSearch.

In a terminal, paste:

Copy

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

This generates a folder structure on your machine:

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

create-instantsearch-app provides the index data, all necessary code, and predefined credentials (application ID and API key).

Initialization

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:

Copy

1
2
3
4
5
6
7
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');

1
2
3
4
5
6
7
8
9
10
import Vue from 'vue';
import App from './App.vue';
import InstantSearch from 'vue-instantsearch';

Vue.use(InstantSearch);

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

Add the search user interface code

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

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

Understand the code

In src/App.js, you’ll see several InstantSearch widgets:

ais-instant-search is the root Vue InstantSearch component. All other widgets must be wrapped within this widget
ais-search-box displays a search box for users to type queries into
ais-hits displays the results from Algolia, based on the query.

Run the project

In your terminal, type:

Copy

1
2
cd ais-ecommerce-demo-app
npm start

Open your browser and go to http://localhost:3000.

You’ll see this:

Add more widgets

To enhance your search UI, add these widgets:

ais-clear-refinements displays a button to clear the current refinements
ais-refinement-list displays a list of brands to filter the search
ais-configure passes search parameters. In this example, it sets the hitsPerPage to 8. It doesn’t render anything to the DOM itself.
ais-pagination implements paging logic

Open the file src/App.vue and update it:

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

Alter the styling

The widgets have a predefined style but this can be altered.

To create a two-column layout, replace the content of the style tag with:

Copy
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;
}

In your browser, after a page refresh, you’ll see this:

Customize hits

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

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

Add formatting

Update the content of the style tag with:

Copy
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;
}

In your browser, after a page refresh, you’ll see this:

For more information about customization, see Customize an existing widget.

Configure the dataset

First:

Download the dataset
Set up an API client and send your data to Algolia
Configure the index with the following code:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
$index->setSettings(array(
  "searchableAttributes" => [
    "brand",
    "name",
    "categories",
    "unordered(description)"
  ],
  "customRanking" => [
    "desc(popularity)"
  ],
  "attributesForFaceting" => [
    "searchable(brand)",
    "type",
    "categories",
    "price"
  ]
));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
index.set_settings(
  searchableAttributes: [
    'brand',
    'name',
    'categories',
    'unordered(description)'
  ],
  customRanking: [
    'desc(popularity)'
  ],
  attributesForFaceting: [
    'searchable(brand)',
    'type',
    'categories',
    'price'
  ]
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
index.setSettings({
   searchableAttributes: [
    'brand',
    'name',
    'categories',
    'unordered(description)'
  ],
  customRanking: [
    'desc(popularity)'
  ],
  attributesForFaceting: [
    'searchable(brand)',
    'type',
    'categories',
    'price'
  ]
}).then(() => {
  // done
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
index.set_settings({
    'searchableAttributes': [
        'brand',
        'name',
        'categories',
        'unordered(description)'
    ],
    'customRanking': [
        'desc(popularity)'
    ],
    'attributesForFaceting': [
        'searchable(brand)',
        'type',
        'categories',
        'price'
    ]
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
index.setSettings([
  "searchableAttributes": [
  "brand",
  "name",
  "categories",
  "unordered(description)"
  ],
  "customRanking": [
    "desc(popularity)"
  ],
  "attributesForFaceting": [
    "searchable(brand)",
    "type",
    "categories",
    "price"
  ]
])

1
2
3
4
5
6
7
8
IndexSettings settings = new IndexSettings
{
    SearchableAttributes = new List<string> {"brand", "name", "categories", "description"},
    CustomRanking = new List<string> {"desc(popularity)"},
    UnretrievableAttributes = new List<string> {"searchable(brand)", "type", "categories", "price"}
};

index.SetSettings(settings);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
index.setSettings(
  new IndexSettings().setSearchableAttributes(Arrays.asList(
    "brand",
    "name",
    "categories",
    "unordered(description)"
  )).setCustomRanking(Arrays.asList(
    "desc(popularity)"
  )).setAttributesForFaceting(Arrays.asList(
    "searchable(brand)",
    "type",
    "categories",
    "price"
  ))
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
res, err := index.SetSettings(search.Settings{
  SearchableAttributes: opt.SearchableAttributes(
    "brand",
    "name",
    "categories",
    "unordered(description)",
  ),
  CustomRanking: opt.CustomRanking(
    "desc(popularity)",
  ),
  AttributesForFaceting: opt.AttributesForFaceting(
    "searchable(brand)",
    "type",
    "categories",
    "price",
  ),
})

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
val result: Future[Task] = client.execute {
    setSettings of "myIndex" `with` IndexSettings(
      searchableAttributes = Some(Seq(
        SearchableAttributes.attribute("brand"),
        SearchableAttributes.attribute("name"),
        SearchableAttributes.attribute("categories"),
        SearchableAttributes.unordered("description")
      )),
      customRanking = Some(Seq(
        CustomRanking.desc("popularity")
      )),
      attributesForFaceting = Some(Seq(
        "searchable(brand)",
        "type",
        "categories",
        "price"
      ))
    )
  }

Installation

Click and conversion events

Did you find this page helpful?

Getting started with Vue InstantSearch

On this page

Before you begin

Tutorial

Add starter code

Initialization

Add the search user interface code

Understand the code

Run the project

Add more widgets

Alter the styling

Customize hits

Add formatting

Configure the dataset

On this page