API Reference / Vue InstantSearch Widgets / ais-hits
Apr. 24, 2019

ais-hits

Widget signature 
<ais-hits
  // Optional parameters
  :escapeHTML="boolean"
  :class-names="object"
  :transform-items="function"
/>
See code examples
See Live example

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

Copy
1

<ais-hits />

Props

escapeHTML
type: boolean
default: true
Optional

Whether to escape HTML entities from hits string values.
Copy
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.
Copy
1
2
3
4
5
6
7

<ais-hits
  :class-names="{
    'ais-Hits': 'MyCustomHits',
    'ais-Hits-list': 'MyCustomHitsList',
    // ...
  }"
/>
transform-items
type: function
default: x => x
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.
Copy
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.
Copy
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.
Copy
1
2
3
4
5

<ais-hits>
  <div slot="item" slot-scope="{ item, index }">
    {{ index }} - {{ item.name }}
  </div>
</ais-hits>

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

Copy
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.1.1";

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

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

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

Copy
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

Copy
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

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

HTML output

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

Did you find this page helpful?

Vue InstantSearch v2