API Reference / Vue InstantSearch Widgets / ais-hits
Widget signature
<ais-hits
  // Optional parameters
  :escapeHTML="boolean"
  :class-names="object"
  :transform-items="function"
/>

About this widget

The ais-hits is used to display a list of results.

To configure the number of hits to show, use the ais-hits-per-page widget or the ais-configure widget.

Examples

1
<ais-hits />

Props

escapeHTML
type: boolean
default: true
Optional

Whether to escape HTML entities from hits string values.

1
<ais-hits :escapeHTML="false" />
class-names
type: object
default: {}
Optional

The CSS classes to override.

  • ais-Hits: the root element of the widget.
  • ais-Hits-list: the list of results.
  • ais-Hits-item: the list items.
1
2
3
4
5
6
7
<ais-hits
  :class-names="{
    'ais-Hits': 'MyCustomHits',
    'ais-Hits-list': 'MyCustomHitsList',
    // ...
  }"
/>
transform-items
type: function
default: items => items
Optional

Receives the items, and is called before displaying them. Should return a new array with the same shape as the original array. Useful for mapping over the items to transform, and remove or reorder them.

If you’re transforming an attribute using the ais-highlight widget, you need to transform item._highlightResult[attribute].value.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<template>
  <!-- ... -->
  <ais-hits :transform-items="transformItems" />
</template>

<script>
  export default {
    methods: {
      transformItems(items) {
        return items.map(item => ({
          ...item,
          name: item.name.toUpperCase(),
        }));
      },
    },
  };
</script>

Customize the UI

default

The slot to override the complete DOM output of the widget.

Scope

  • items: object[]: the records that matched the search.
1
2
3
4
5
6
7
<ais-hits>
  <ul slot-scope="{ items }">
    <li v-for="item in items" :key="item.objectID">
      {{ item.name }}
    </li>
  </ul>
</ais-hits>
item

The slot to override the DOM output of the item.

Scope

  • items: object: a single hit with all its attributes.
  • index: number: the relative position of the hit in the list.
1
2
3
4
5
<ais-hits>
  <div slot="item" slot-scope="{ item, index }">
    {{ index }} - {{ item.name }}
  </div>
</ais-hits>

HTML output

1
2
3
4
5
6
7
8
9
10
11
12
13
<div class="ais-Hits">
  <ol class="ais-Hits-list">
    <li class="ais-Hits-item">
      ...
    </li>
    <li class="ais-Hits-item">
      ...
    </li>
    <li class="ais-Hits-item">
      ...
    </li>
  </ol>
</div>

Sending Click and Conversion events

InstantSearch can connect with the Insights API client for JavaScript to allow sending click and conversion events right from the ais-hits widget.

Requirements

This requires installing the search-insights library separately:

You can refer to our insights API documentation for more details.

It’s a 3-step process:

1. Install the Insights API client for JavaScript

1
2
3
4
5
6
7
8
9
10
11
12
13
<script>
  var ALGOLIA_INSIGHTS_SRC = "https://cdn.jsdelivr.net/npm/search-insights@1.6.3";

  !function(e,a,t,n,s,i,c){e.AlgoliaAnalyticsObject=s,e[s]=e[s]||function(){
  (e[s].queue=e[s].queue||[]).push(arguments)},i=a.createElement(t),c=a.getElementsByTagName(t)[0],
  i.async=1,i.src=n,c.parentNode.insertBefore(i,c)
  }(window,document,"script",ALGOLIA_INSIGHTS_SRC,"aa");

  aa('init', {
    appId: 'YourApplicationID',
    apiKey: 'YourSearchOnlyAPIKey',
  });
</script>

2. Connect the Insights API client for JavaScript with InstantSearch and enable clickAnalytics

1
2
3
4
5
6
7
<ais-instant-search 
  [...] 
  :insights-client="window.aa"
>
  <ais-configure :clickAnalytics="true" />
  <!-- widgets -->
</ais-instant-search>

3. Call the insights function from your ais-hits component

1
2
3
4
5
6
7
8
9
10
<ais-hits>
  <div slot-scope="{ items, insights }">
    <div v-for="item in items">
      <h1>{{item.name}}</h1>
      <button @click="insights('clickedObjectIDsAfterSearch', { eventName: 'Add to cart', objectIDs: [item.objectID] })">
        Add to cart
      </button>
    </div>
  </div>
</ais-hits>

Provided props

insights
type: function
signature: (method: string, payload: object) => void

Sends insights events.

  • method: string: the insights method to be called. Only search-related methods are supported: 'clickedObjectIDsAfterSearch', 'convertedObjectIDsAfterSearch'.

  • payload: object: the payload to be sent.

    • eventName: string: the name of the event.
    • objectIDs: string[]: a list of objectIDs.
    • index?: string: the name of the index related to the click.
    • queryID?: string: the Algolia queryID that can be found in the search response when using clickAnalytics: true.
    • userToken?: string: a user identifier.
    • positions?: number[]: the position of the click in the list of Algolia search results.

When not provided, index, queryID, and positions are inferred by the InstantSearch context and the passed objectIDs:

  • index by default is the name of index that returned the passed objectIDs.
  • queryID by default is the ID of the query that returned the passed objectIDs.
  • positions by default is the absolute positions of the passed objectIDs.

It is worth noting that each element of items has the following read-only properties:

  • __queryID: the query ID (only if clickAnalytics is set to true).
  • __position: the absolute position of the item.

For more details on the contraints that apply to each payload property, please refer to the insights client documentation.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
<ais-hits>
  <div slot-scope="{ items, insights }">
    <div v-for="item in items">
      <a href="/product?queryID={{item.__queryID}}">
        <h1>{{item.name}}</h1>
      </a>

      <button @click="insights('clickedObjectIDsAfterSearch', { eventName: 'Add to cart', objectIDs: [item.objectID] })">
        Add to cart
      </button>
    </div>
  </div>
</ais-hits>

Did you find this page helpful?