API Reference / Vue InstantSearch / ais-instant-search

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-client: function
/>
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 the credentials for the search. This component automatically provides the search state to all its children.

Note that every other Vue InstantSearch widgets must be wrapped under this one.

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

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. To implement a custom search client, take a look at a the custom back-end 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

<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

A hook that is called each time a search needs to be done, with the helper as a parameter. It’s your responsibility to call helper.search(). This option allows you, for example, to avoid doing searches at page load.

When modifying the state of the helper within search-function, the helper automatically reset 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.

When this option is set, search.helper will no longer emit events, as it’s considered “controlled”. Instead you can either use on-state-change or widgets to handle that behavior.
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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

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

// Example which avoids the page to be reset to 0
<script>
  export default {
    data() {
      return {
        // ...
        searchFunction(helper) {
          const page = helper.getPage(); // Retrieve the current page

          helper.setQuery('Hello') // this call resets the page
                .setPage(page) // we re-apply the previous page
                .search();
        },
      };
    }
  };
</script>
on-state-change
type: function
Optional

Triggers when the state changes.

Whenever you start using this option, the instance becomes controlled. This means that you become responsible for updating the UI state with setUiState.

This can be useful to perform custom logic whenever the state changes.
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
26
27
28
29
30
31
32
33
34
35
36
37
38
39

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

// Example which avoids the page to be reset to 0
<script>
  export default {
    data() {
      return {
        // ...
        onStateChange({ uiState, setUiState }) {
          // Custom logic

          setUiState(uiState);
        },
      };
    }
  };
</script>
stalled-search-delay
type: number
default: 200
Optional

Defines a time period after which a search is considered stalled. You can find more information in the slow network guide.
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. You can find more information in the routing guide. 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 (e.g. 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, and returns an object.
    • write: function: pushes routeState into a 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 that is saved by the router. The default value is provided by simple. It accepts:
    • stateToRoute: function: transforms a uiState representation into routeState. It receives an object that contains the UI state of all the widgets in the page. It can return any object that is readable by routeToState.
    • routeToState: function: transforms routeState into a uiState representation. It receives an object that contains the UI state stored by the router. It can return any object that is readable by stateToRoute.
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 lets you provide an initial state to your widgets. To apply the uiState to the search parameters, you must add your widgets inside your ais-instant-search component.
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: {
        indexName: {
          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-client
type: function
Optional

The function exposed by the search-insights (usually window.aa). This is needed if you want to send click and conversion events with InstantSearch.
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>

HTML output

Copy 
1
2
3

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