Skip to main content
Signature
<ais-instant-search
  index-name="string"
  :search-client="object"
  // Optional parameters
  :on-state-change="function"
  :search-function="function"
  :stalled-search-delay="number"
  :routing="object"
  :initial-ui-state="object"
  :class-names="object"
  :insights="boolean | object"
  :insights-client="function"
  :future="{
    preserveSharedStateOnUnmount: boolean,
    persistHierarchicalRootCount: boolean,
  }"
/>

​
Import

You can import this widget in two ways.
  • Component
  • Plugin
To ensure optimal bundle sizes, see Optimize build size.
Vue
import { AisInstantSearch } from "vue-instantsearch";
// Use "vue-instantsearch/vue3/es" for Vue 3

export default {
  components: {
    AisInstantSearch,
  },
  // ...
};
View demo

​
About this widget

ais-instant-search is the root wrapper component for all widgets.

​
Middleware

Vue InstantSearch provides middleware to help you connect to other systems:

​
Examples

Vue
<template>
  <ais-instant-search
    index-name="INDEX_NAME"
    :search-client="searchClient"
  >
    <!-- Widgets -->
  </ais-instant-search>
</template>

<script>
import { liteClient as algoliasearch } from "algoliasearch/lite";

export default {
  data() {
    return {
      searchClient: algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey"),
    };
  },
};
</script>

​
Props

​
index-name
string
required
The main index in which to search.
Vue
<ais-instant-search
  [...]
  index-name="INDEX_NAME"
>
  <!-- Widgets -->
</ais-instant-search>
​
search-client
object
required
Provides a search client to ais-instant-search. Read the custom backend guidance on implementing a custom search client.The client uses a cache to avoid unnecessary search operations, so you should use a stable reference to the same search client instance rather than creating a new one on each render. Avoid inlining the function call to algoliasearch as the prop value in your Vue template.
Vue
<template>
  <ais-instant-search
    [...]
    :search-client="searchClient"
  >
    <!-- Widgets -->
  </ais-instant-search>
</template>

<script>
import { liteClient as algoliasearch } from "algoliasearch/lite";

export default {
  data() {
    return {
      searchClient: algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey"),
    };
  },
};
</script>
​
search-function
function
This option allows you to take control of search behavior. For example, to avoid doing searches at page load.When this option is set, search.helper won’t emit events. Instead, use on-state-change or widgets to handle search behavior.A hook is called each time a search is requested (with Algolia’s helper API as a parameter). Begin searching by calling helper.search().When modifying the state of the helper within search-function, the helper resets the page to 0. To keep the current page, store the page information, modify the state, and reapply pagination.
<template>
  <ais-instant-search
    [...]
    :search-function="searchFunction"
  >
    <!-- Widgets -->
  </ais-instant-search>
</template>

<script>
export default {
  data() {
    return {
      // ...
      searchFunction(helper) {
        if (helper.state.query) {
          helper.search();
        }
      },
    };
  },
};
</script>
​
on-state-change
function
Triggers when the state changes. This can be useful when performing custom logic on a state change.When using on-state-change, the instance is under your control. You’re responsible for updating the UI state (with setUiState).
Vue
<template>
  <ais-instant-search
    [...]
    :on-state-change="onStateChange"
  >
    <!-- Widgets -->
  </ais-instant-search>
</template>

<script>
export default {
  data() {
    return {
      // ...
      onStateChange({ uiState, setUiState }) {
        // Custom logic

        setUiState(uiState);
      },
    };
  },
};
</script>
​
stalled-search-delay
number
default:200
A time period (in ms) after which the search is considered to have stalled. Read the slow network guide for more information.
Vue
<ais-instant-search
  [...]
  :stalled-search-delay="1000"
>
  <!-- Widgets -->
</ais-instant-search>
​
routing
boolean | object
default:false
The router configuration used to save the UI state into the URL or any client-side persistence.For more information, see Sync your URLs.You can’t use initialUiState with routing as the two options override each other.
  • Use initialUiState for simple and static use cases.
  • Use routing for anything complex or dynamic.
Vue
<template>
  <ais-instant-search
    [...]
    :routing="routing"
  >
    <!-- Widgets -->
  </ais-instant-search>
</template>

<script>
import { history } from "instantsearch.js/es/lib/routers";
import { simple } from "instantsearch.js/es/lib/stateMappings";

export default {
  data() {
    return {
      // ...
      routing: {
        router: history(),
        stateMapping: simple(),
      },
    };
  },
};
</script>
​
initial-ui-state
object
Adds a uiState to your ais-instant-search instance, which provides an initial state to your widgets.Replace YourIndexName with the name of your Algolia index.
Vue
<template>
  <ais-instant-search
    :initial-ui-state="initialUiState"
  ></ais-instant-search>
</template>

<script>
export default {
  data() {
    return {
      // ...
      initialUiState: {
        YourIndexName: {
          query: "phone",
          page: 5,
        },
      },
    };
  },
};
</script>
​
class-names
object
default:"{}"
The CSS classes you can override:
  • ais-InstantSearch: the root of the widget.
Vue
<ais-instant-search
  [...]
  :class-names="{
    'ais-InstantSearch': 'MyCustomInstantSearch',
  }"
>
  <!-- Widgets -->
</ais-instant-search>
​
insights
boolean | object
default:false
since: v4.9.0
Enables the Insights middleware and loads the search-insights library (if not already loaded). The Insights middleware sends view and click events automatically, and lets you set up your own click and conversion events. To use this option with an object, refer to the Insights middleware options.
<ais-instant-search
  [...]
  :insights="true"
>
  <!-- Widgets -->
</ais-instant-search>
​
insights-client
function
deprecated
Use insights instead.This function is exposed by the search-insights library (usually window.aa) and is required if you want to send click and conversion events with the insights middleware.
Vue
<template>
  <ais-instant-search
    [...]
    :insights-client="insightsClient"
  >
    <!-- Widgets -->
  </ais-instant-search>
</template>

<script>
export default {
  data() {
    return {
      // ...
      insightsClient: window.aa,
    };
  },
};
</script>
​
future
object
Test new InstantSearch features without affecting others.

​
HTML output

HTML
<div class="ais-InstantSearch">
  <!-- Widgets -->
</div>
⌘I