🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
UI libraries / Vue InstantSearch / Widgets

ais-instant-search

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
Copy 
1
2
3
4
5
6
7
8
9

import { AisInstantSearch } from 'vue-instantsearch';
// Use 'vue-instantsearch/vue3/es' for Vue 3

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

1. Follow additional steps in Optimize build size to ensure your code is correctly bundled.
2. This imports all the widgets, even the ones you don’t use. Read the Getting started guide for more information.

See code examples
See live example

About this widget

The ais-instant-search widget is a wrapper that allows you to configure your search. It provides the search state to all its children.

You must wrap all other Vue InstantSearch widgets inside this one.

Middleware

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

Examples

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

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

<script>
  import algoliasearch from 'algoliasearch/lite';

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

Props

Parameter Description
index-name
type: string
Required

The main index in which to search.
Copy 
1
2
3
4
5
6

<ais-instant-search
  [...]
  index-name="instant_search"
>
  <!-- Widgets -->
</ais-instant-search>
search-client
type: 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.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<template>
  <ais-instant-search
    [...]
    :search-client="searchClient"
  >
    <!-- Widgets -->
  </ais-instant-search>
</template>

<script>
  import algoliasearch from 'algoliasearch/lite';

  export default {
    data() {
      return {
        searchClient: algoliasearch(
          'YourApplicationID',
          'YourSearchOnlyAPIKey'
        ),
      };
    }
  };
</script>
search-function
type: function
Optional

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). Carry out the search by calling helper.search().

When modifying the state of the helper within search-function, the helper resets the page to 0. If you want to keep the current page, you need to store the information about the page, modify the state and reapply the pagination.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<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
type: function
Optional

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).
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

<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
type: number
default: 200
Optional

A time period (in ms) after which the search is considered to have stalled. Read the slow network guide for more information.
Copy 
1
2
3
4
5
6

<ais-instant-search
  [...]
  :stalled-search-delay="1000"
>
  <!-- Widgets -->
</ais-instant-search>
routing
type: object
default: undefined
Optional

The router configuration used to save the UI state into the URL or any client-side persistence. The object is accepted if it has either of these keys:

  • router: object: this object is the part that saves the UI state. By default, it uses an instance of the history with the default parameters. It accepts:
    • onUpdate: function: adds an event listener that makes InstantSearch aware of external changes to the storage medium (such as the URL). Typically you’ll set up a listener for popstate, which triggers a callback with the current routeState.
    • read: function: reads the routing storage and gets routeState. It doesn’t take any parameters but returns an object.
    • write: function: pushes routeState into routing storage.
    • createURL: function: transforms routeState into a URL. It receives an object and returns a string (which may be empty).
    • dispose: function: cleans up all event listeners.
  • stateMapping: object: transforms the uiState into the object saved by the router. The default value is provided by simple. It accepts:
    • stateToRoute: function: transforms a ui-state representation into routeState. It receives an object that contains the UI state of all the widgets on the page. It can return any object that is readable by routeToState.
    • routeToState: function: transforms routeState into a ui-state representation. It receives an object that contains the UI state stored by the router. It can return any object that is readable by stateToRoute.

For more information, read the routing guide.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

<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
type: object
Optional

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.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

<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
type: object
default: {}
Optional

The CSS classes to override.

  • ais-InstantSearch: the root of the widget.
Copy 
1
2
3
4
5
6
7
8

<ais-instant-search
  [...]
  :class-names="{
    'ais-InstantSearch': 'MyCustomInstantSearch',
  }"
>
  <!-- Widgets -->
</ais-instant-search>
insights
since: v4.9.0
type: boolean|object
default: false
Optional

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.
Copy 
1
2
3
4
5
6

<ais-instant-search
  [...]
  :insights="true"
>
  <!-- Widgets -->
</ais-instant-search>
insights-client
Deprecated
type: function
Optional

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.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<template>
  <ais-instant-search
    [...]
    :insights-client="insightsClient"
  >
    <!-- Widgets -->
  </ais-instant-search>
</template>

<script>
  export default {
    data() {
      return {
        // ...
        insightsClient: window.aa
      };
    }
  };
</script>
future
type: object
Optional

This option lets you try out new InstantSearch features without affecting the current experience for everyone else.

See below for more information on individual future options.
preserveSharedStateOnUnmount
since: v4.11.0
type: boolean
default: false
Optional

Changes the way dispose is used in InstantSearch lifecycle.

If false (the default), each widget unmounting will also remove its state, even if multiple widgets read that UI state.

If true, each widget unmounting will only remove its state if it’s the last of its type. This allows you to dynamically add and remove widgets without losing their state.
Copy 
1
2
3
4
5
6
7
8
9
10

<template>
  <ais-instant-search
    [...]
    :future="{
      preserveSharedStateOnUnmount: true,
    }"
  >
    <!-- Widgets -->
  </ais-instant-search>
</template>
persistHierarchicalRootCount
since: v4.13.1
type: boolean
default: false
Optional

Whether to display a constant facet value count at the root of a hierarchical menu with active refinements.

If false (default), the facet value count at the root level shows the facet value count of the refined (child) facet’s parent.

If true, the facet value count at the root level shows the sum of the facet value counts of all its children, with or without refined children.
Copy 
1
2
3
4
5
6
7
8
9
10

<template>
  <ais-instant-search
    [...]
    :future="{
      persistHierarchicalRootCount: true,
    }"
  >
    <!-- Widgets -->
  </ais-instant-search>
</template>

HTML output

Copy 
1
2
3

<div class="ais-InstantSearch">
  <!-- Widgets -->
</div>
Did you find this page helpful?
Vue InstantSearch v4