Vue InstantSearch

Common errors

• [Vue warn]: Component <AisInstantSearch> is missing template or render function.

  cause An InstantSearch widget component (e.g., `AisInstantSearch`, `AisSearchBox`) was not correctly imported or registered in your Vue application.
  fix Ensure that components are imported as named exports (e.g., `import { InstantSearch } from 'vue-instantsearch';`) and then either registered globally (`app.component('AisInstantSearch', InstantSearch)` for Vue 3, or `Vue.component('AisInstantSearch', InstantSearch)` for Vue 2) or locally within your component's `components` option.

• TypeError: Cannot read properties of undefined (reading 'init') at VueComponent.mounted

  cause The `searchClient` prop passed to `<ais-instant-search>` is `undefined` or not a valid Algolia search client instance.
  fix Verify that `algoliasearch/lite` is imported, correctly initialized with valid Algolia credentials (App ID and Search API Key), and then properly passed to the `<ais-instant-search>` component via the `:search-client` prop. Ensure it's not the Admin API Key.

• Uncaught (in promise) Error: You must provide an 'indexName' to the InstantSearch component.

  cause The required `indexName` prop is missing or empty on the `<ais-instant-search>` root component.
  fix Add the `:index-name="'your_algolia_index_name'"` prop to your `<ais-instant-search>` component, providing a valid Algolia index name that you wish to search.

Warnings

• breaking Migrating a Vue InstantSearch project from Vue 2 to Vue 3 can involve several breaking changes, particularly concerning component registration, slot syntax, and reactivity system differences. While `vue-instantsearch` supports both, the underlying Vue.js changes require attention.
  Fix: Review the official Vue 3 migration guide and the Vue InstantSearch documentation's 'Vue 2 vs Vue 3' section. Pay close attention to `app.use()` vs `Vue.use()`, `v-model` behavior, `slot` syntax, and removal of APIs like filters.
• gotcha Using an `algoliasearch` client version outside the specified peer dependency range (`>= 3.32.0 < 6`) can lead to runtime errors or unexpected behavior due to API inconsistencies with the underlying Algolia client.
  Fix: Ensure your installed `algoliasearch` package strictly adheres to the peer dependency requirements of `vue-instantsearch`. Use `npm install --legacy-peer-deps` or `npm install --force` with caution if resolution conflicts occur, and ideally, update all related packages to compatible versions.
• gotcha Server-side rendering (SSR) with Vue InstantSearch requires specific setup, including proper integration of `@vue/server-renderer` (Vue 3) or `vue-server-renderer` (Vue 2), and careful state hydration. Incorrect configuration often results in non-hydrated content or runtime errors.
  Fix: Consult the dedicated SSR guides in the Vue InstantSearch documentation. Ensure the `createServerRootMixin` (for Vue 2) or `serverPrefetch` (for Vue 3) is correctly implemented and that the initial search state is properly hydrated on the client-side.
• breaking Breaking changes in the underlying `instantsearch.js` library (e.g., from v3 to v4) directly affect `vue-instantsearch`'s behavior and API, even if `vue-instantsearch`'s major version does not increment simultaneously. Developers should review `instantsearch.js` changelogs.
  Fix: Always check the `instantsearch.js` release notes and migration guides when updating `vue-instantsearch` or `instantsearch.js`. Be aware of changes to widgets, connectors, or core API interactions. `vue-instantsearch` v4 is built on `instantsearch.js` v4.
• deprecated The `search-insights` library and the `insights` middleware for event tracking have been deprecated in favor of a simpler `insights` option on the `ais-instant-search` component. Continued use of the old middleware is discouraged.
  Fix: Upgrade `vue-instantsearch` to v4.9.0 or greater. Remove the `search-insights` library and insights middleware, then configure event tracking by setting the `insights` option to `true` (or an object for advanced customization) on the `<ais-instant-search>` component.

Install

• npm install vue-instantsearch npm
• yarn add vue-instantsearch yarn
• pnpm add vue-instantsearch pnpm

Imports

• InstantSearch
  wrong:

  import InstantSearch from 'vue-instantsearch';

  correct:

  import { InstantSearch } from 'vue-instantsearch';

  The `InstantSearch` component is a named export and serves as the root wrapper for all other Algolia InstantSearch widgets.
• SearchBox
  wrong:

  import { AisSearchBox } from 'vue-instantsearch';

  correct:

  import { SearchBox } from 'vue-instantsearch';

  Individual widget components like `SearchBox` are imported by their PascalCase name. In Vue templates, they are typically used with an `ais-` prefix (e.g., `<ais-search-box />`).
• connectSearchBox
  wrong:

  import { connectSearchBox } from 'instantsearch.js/es/connectors';

  correct:

  import { connectSearchBox } from 'vue-instantsearch';

  For creating custom widgets and advanced logic, `vue-instantsearch` provides its own set of connectors (e.g., `connectSearchBox`), which are tailored for Vue's reactivity system and integrate directly with the `ais-instant-search` context.

Quickstart

This quickstart demonstrates a basic Algolia search interface in a Vue 3 application using Vue InstantSearch components: `ais-instant-search` as the root, `ais-search-box` for query input, and `ais-hits` to display results with a simple template. It initializes `algoliasearch/lite` with environment variables for security.

import { createApp, h } from 'vue';
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, SearchBox, Hits, Configure } from 'vue-instantsearch';
import 'instantsearch.css/themes/satellite-min.css'; // Or another theme, e.g., algolia-min.css

const searchClient = algoliasearch(
  process.env.VUE_APP_ALGOLIA_APP_ID ?? 'YOUR_APP_ID', // Replace with your Algolia Application ID
  process.env.VUE_APP_ALGOLIA_SEARCH_API_KEY ?? 'YOUR_SEARCH_API_KEY' // Replace with your Algolia Search-only API Key
);

const App = {
  components: {
    'ais-instant-search': InstantSearch,
    'ais-search-box': SearchBox,
    'ais-hits': Hits,
    'ais-configure': Configure,
  },
  data() {
    return {
      searchClient,
      indexName: 'instant_search', // Replace with your Algolia index name
    };
  },
  template: `
    <div id="app">
      <ais-instant-search :search-client="searchClient" :index-name="indexName">
        <ais-configure :hits-per-page="8" />
        <header>
          <h1>Vue InstantSearch Demo</h1>
          <ais-search-box placeholder="Search products..." />
        </header>
        <main>
          <ais-hits>
            <template v-slot:item="{ item }">
              <article>
                <h2>{{ item.name }}</h2>
                <p>{{ item.description }}</p>
                <p>Price: $\${{ item.price }}</p>
              </article>
            </template>
          </ais-hits>
        </main>
      </ais-instant-search>
    </div>
  `,
};

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