Registry / web-framework / vue-instantsearch

vue-instantsearch

library4.24.4jsnpmunverified

Vue InstantSearch is a front-end library built by Algolia, offering a comprehensive set of UI components to integrate Algolia's lightning-fast search capabilities into Vue.js applications. It provides a declarative, component-based approach for building search UIs, abstracting away much of the complexity of the Algolia API. The current stable version is 4.24.4, with releases typically following the monorepo's synchronized cadence, often with minor version bumps or 'Note: Version bump only' entries across multiple InstantSearch packages. Its key differentiators include deep integration with the Algolia ecosystem, robust support for both Vue 2 (2.6.0+) and Vue 3 (3.0.0+), and a rich collection of pre-built, customizable widgets for common search features like search boxes, hit lists, facets, and pagination. This allows developers to quickly construct powerful search experiences with minimal effort, focusing on customization rather than boilerplate.

web-framework http-networking

npm install vue-instantsearch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE-INSTANTSEARCH

vue-instantsearch

web-frameworkjavascriptv4.24.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

InstantSearch

✓ import { InstantSearch } from 'vue-instantsearch';

✗ 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

✓ import { SearchBox } from 'vue-instantsearch';

✗ import { AisSearchBox } 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

✓ import { connectSearchBox } from 'vue-instantsearch';

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

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.

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

Debug

Known issues

breakingMigrating 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.

affects: >=4.0.0

gotchaUsing 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.

affects: >=4.0.0

gotchaServer-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.

affects: >=4.0.0

breakingBreaking 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.

affects: >=4.0.0

deprecatedThe `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.

affects: >=4.9.0

Errors

Common errors & fixes

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

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

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.

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.

Upgrade

Version history

4.24.4latest on npm

Audit

Dependencies

@vue/server-rendereroptionalOptional peer dependency for server-side rendering (SSR) with Vue 3 applications.

algoliasearchrequiredEssential peer dependency for connecting to the Algolia API. Must be within the specified version range to ensure compatibility.

vuerequiredCore Vue.js framework dependency, supporting both Vue 2 and Vue 3.

vue-server-rendereroptionalOptional peer dependency for server-side rendering (SSR) with Vue 2 applications.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/algolia/instantsearch ↗

packagehttps://www.npmjs.com/package/vue-instantsearch ↗

homepagehttps://www.algolia.com/doc/guides/building-search-ui/what-is-instantsearch/vue/ ↗