API Reference / Vue InstantSearch / ais-hits

ais-hits

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

About this widget

Use the ais-hits widget 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.

For guidance on how to search across more than one index, read the multi-index search guide.

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: 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 transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).

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

When using an array, take steps to avoid creating infinite loops. When you use an array as a prop, it causes the widget to re-register on every render, and this can sometimes cause these infinite loops.
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-hits :transform-items="transformItems" />
</template>

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

      /* or, combined with results */
      transformItems(items, { results }) {
        return items.map((item, index) => ({
          ...item,
          position: { index, page: results.page },
        }));
      },
    },
  };
</script>

Customize the UI

default

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

Note that when you implement this slot, none of the other slots will change the output, as the default slot surrounds them.

Scope

  • items: object[]: the records that matched the search.
  • sendEvent: (eventType, hit, eventName) => void: the function to send click or conversion events. The view event is automatically sent when this connector renders hits. You can learn more about the insights middleware.
    • eventType: 'click' | 'conversion'
    • hit: Hit | Hit[]
    • eventName: string
  • insights: (method: string, payload: object) => void: (Deprecated) 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’s 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 constraints that apply to each payload property, please refer to the insights client documentation.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<ais-hits>
  <template v-slot="{ items, sendEvent }">
    <ul>
      <li v-for="item in items" :key="item.objectID">
        <h1>{{ item.name }}</h1>
        <button
          type="button"
          @click="sendEvent('click', item, 'Item Added')"
        >
          Add to cart
        </button>
      </li>
    </ul>
  </template>
</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>
  <template v-slot:item="{ item, index }">
    {{ index }} - {{ item.name }}
  </template>
</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>

Sending Click and Conversion events

Please refer to the guide on Sending Insight Events to learn about sending events from any InstantSearch widget.

Guides Send Events with Vue InstantSearch
Did you find this page helpful?
Vue InstantSearch v4