API Reference / Vue InstantSearch Widgets / ais-instant-search

ais-instant-search

Widget signature 
<ais-instant-search
  index-name="string"
  :search-client="object"
  // Optional parameters
  :search-function: function
  :stalled-search-delay="number"
  :routing="object"
  :initial-ui-state="object"
  :class-names="object"
  :insights-client: function
/>
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.
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>
stalled-search-delay
type: number
default: 200
Optional

The amount of time before considering that the search is 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 v3