Essentials Getting started

Edit this page

Getting started

Welcome to Vue InstantSearch

Vue InstantSearch is the ultimate toolbox for creating instant-search experiences using Vue.js and Algolia.

Setup a new Vue project

We’ll use the official vue-cli to bootstrap a new Vue project, along with the webpack-simple template.

$ npm install --global vue-cli
$ vue init webpack-simple vue-instantsearch-getting-started

Info: Default settings are enough, hit Enter ⏎ at every question.

Then install the dependencies of your new project:

$ cd vue-instantsearch-getting-started
$ npm install

Install vue-instantsearch

Add Vue InstantSearch as a dependency, it’s published on npm:

$ npm install --save vue-instantsearch

Run the development environment

When vue-cli bootstrapped the project, it added some npm scripts to your project, like a dev one. Let’s use it:

$ npm run dev

This should open a new tab in your browser with this inside:

Screenshot showing the new tab preview when npm run dev starts.

Leave the dev script running, we will update the code and it will reload in your browser automatically.

Use the InstantSearch plugin

Now we need to tell Vue to use the Vue InstantSearch plugin so that all search components are available in our templates.

Open the src/main.js entry point and replace the existing content with the following:

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

From now on, you can use all Vue InstantSearch components in your templates throughout the whole application.

Create your first search experience

Let’s bootstrap a small search interface.

Open the src/App.vue component. Then replace the whole beginning of the file, between the <template></template> tags, with the following:

<template>
  <ais-index
    app-id="latency"
    api-key="3d9875e51fbd20c7754e65422f7ce5e1"
    index-name="bestbuy"
  >
    <ais-search-box></ais-search-box>
    <ais-results>
      <template slot-scope="{ result }">
        <h2>
          <ais-highlight :result="result" attribute-name="name"></ais-highlight>
        </h2>
      </template>
    </ais-results>
  </ais-index>
</template>

Save, and see the result in the browser. Play with it!

Animated screenshot showing a first search experience.

How it works

In this section you’ll learn a bit more about what you just implemented.

The Index component

All search components needs to be wrapped in an Index component.

<ais-index
  app-id="latency"
  api-key="3d9875e51fbd20c7754e65422f7ce5e1"
  index-name="bestbuy"
>
  <!-- Search components go here -->
</ais-index>

You should configure the Index component with the application ID and API search only key.

The job of the Index component is to hold the state of the search, and to provide it to child components.

Info: Alternatively you can manually inject a search store, for example to support server-side rendering.

Algolia demo credentials

For the demo, we provided you with some default Algolia credentials:

  • app-id: latency
  • search-key: 3d9875e51fbd20c7754e65422f7ce5e1
  • index-name: bestbuy

When you are ready to go further, you can create your own Algolia account and find your credentials in the Algolia dashboard.

The Search Box component

The Search Box component renders a text input.

The text input value is bound to the query of the current search.

Every time the query changes, the search store will contact Algolia to get the new results for the new query.

Info: The Search Box component is wrapped into a <form> element and provides a reset and submit button by default. These good search practices are explained here.

The Results component

The Results component will loop over all results returned by the Algolia response, and display them.

The component has a default slot so that you can easily define your custom template for the rendering of every single result.

Info: By default, if no slot is provided, the component will display the objectID of every result.

The slot provided by the Results component is a scoped slot.

A scoped slot means that the template can access data passed to the slot.

This is illustrated by this snippet:

<template slot-scope="parameters">
  <h1>{{ parameters.result.name }}</h1>
</template>

or with an ES6 syntax:

<template slot-scope="{ result }">
  <h1>{{ result.name }}</h1>
</template>

Now that result is available, we can customize the html inside the template.

In the example we provided, we display the highlighted version of the name of the result.