{"id":12511,"library":"vue-instantsearch","title":"Vue InstantSearch","description":"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.","status":"active","version":"4.24.4","language":"javascript","source_language":"en","source_url":"https://github.com/algolia/instantsearch","tags":["javascript","vue","algolia","search","instantsearch","components","ui","facet","autocomplete"],"install":[{"cmd":"npm install vue-instantsearch","lang":"bash","label":"npm"},{"cmd":"yarn add vue-instantsearch","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-instantsearch","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Optional peer dependency for server-side rendering (SSR) with Vue 3 applications.","package":"@vue/server-renderer","optional":true},{"reason":"Essential peer dependency for connecting to the Algolia API. Must be within the specified version range to ensure compatibility.","package":"algoliasearch","optional":false},{"reason":"Core Vue.js framework dependency, supporting both Vue 2 and Vue 3.","package":"vue","optional":false},{"reason":"Optional peer dependency for server-side rendering (SSR) with Vue 2 applications.","package":"vue-server-renderer","optional":true}],"imports":[{"note":"The `InstantSearch` component is a named export and serves as the root wrapper for all other Algolia InstantSearch widgets.","wrong":"import InstantSearch from 'vue-instantsearch';","symbol":"InstantSearch","correct":"import { InstantSearch } from 'vue-instantsearch';"},{"note":"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 />`).","wrong":"import { AisSearchBox } from 'vue-instantsearch';","symbol":"SearchBox","correct":"import { SearchBox } from 'vue-instantsearch';"},{"note":"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.","wrong":"import { connectSearchBox } from 'instantsearch.js/es/connectors';","symbol":"connectSearchBox","correct":"import { connectSearchBox } from 'vue-instantsearch';"}],"quickstart":{"code":"import { createApp, h } from 'vue';\nimport algoliasearch from 'algoliasearch/lite';\nimport { InstantSearch, SearchBox, Hits, Configure } from 'vue-instantsearch';\nimport 'instantsearch.css/themes/satellite-min.css'; // Or another theme, e.g., algolia-min.css\n\nconst searchClient = algoliasearch(\n  process.env.VUE_APP_ALGOLIA_APP_ID ?? 'YOUR_APP_ID', // Replace with your Algolia Application ID\n  process.env.VUE_APP_ALGOLIA_SEARCH_API_KEY ?? 'YOUR_SEARCH_API_KEY' // Replace with your Algolia Search-only API Key\n);\n\nconst App = {\n  components: {\n    'ais-instant-search': InstantSearch,\n    'ais-search-box': SearchBox,\n    'ais-hits': Hits,\n    'ais-configure': Configure,\n  },\n  data() {\n    return {\n      searchClient,\n      indexName: 'instant_search', // Replace with your Algolia index name\n    };\n  },\n  template: `\n    <div id=\"app\">\n      <ais-instant-search :search-client=\"searchClient\" :index-name=\"indexName\">\n        <ais-configure :hits-per-page=\"8\" />\n        <header>\n          <h1>Vue InstantSearch Demo</h1>\n          <ais-search-box placeholder=\"Search products...\" />\n        </header>\n        <main>\n          <ais-hits>\n            <template v-slot:item=\"{ item }\">\n              <article>\n                <h2>{{ item.name }}</h2>\n                <p>{{ item.description }}</p>\n                <p>Price: $\\${{ item.price }}</p>\n              </article>\n            </template>\n          </ais-hits>\n        </main>\n      </ais-instant-search>\n    </div>\n  `,\n};\n\ncreateApp(App).mount('#app');","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=4.9.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"An InstantSearch widget component (e.g., `AisInstantSearch`, `AisSearchBox`) was not correctly imported or registered in your Vue application.","error":"[Vue warn]: Component <AisInstantSearch> is missing template or render function."},{"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.","cause":"The `searchClient` prop passed to `<ais-instant-search>` is `undefined` or not a valid Algolia search client instance.","error":"TypeError: Cannot read properties of undefined (reading 'init') at VueComponent.mounted"},{"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.","cause":"The required `indexName` prop is missing or empty on the `<ais-instant-search>` root component.","error":"Uncaught (in promise) Error: You must provide an 'indexName' to the InstantSearch component."}],"ecosystem":"npm"}