Skip to main content
Signature
<ais-hits
  // Optional parameters
  :show-banner="boolean"
  :escapeHTML="boolean"
  :class-names="object"
  :transform-items="function"
/>

​
Import

  • Component
  • Plugin
To ensure optimal bundle sizes, see Optimize build size.
Vue
import { AisHits } from "vue-instantsearch";
// Use "vue-instantsearch/vue3/es" for Vue 3

export default {
  components: {
    AisHits,
  },
  // ...
};
View demo

​
About this widget

Use the ais-hits widget to display a list of results. To set the number of search results, use the ais-hits-per-page or ais-configure widget. See also:

​
Examples

Vue
<ais-hits />

​
Props

​
show-banner
boolean
default:true
Whether to display a top banner when banner data is included within the renderingContent property from the Algolia API response.
Vue
<ais-hits :show-banner="true" />
​
escapeHTML
boolean
default:true
Whether to escape HTML entities from hits string values.
Vue
<ais-hits :escapeHTML="false" />
​
class-names
object
default:"{}"
The CSS classes you can override:
  • ais-Hits. The widget’s root element.
  • ais-Hits-list. The list of results.
  • ais-Hits-item. The list of items.
  • ais-Hits-banner. The optional banner’s root.
  • ais-Hits-banner-image. The image element of the optional banner.
  • ais-Hits-banner-link. The optional anchor element of the optional banner.
Vue
<ais-hits
  :class-names="{
    'ais-Hits': 'MyCustomHits',
    'ais-Hits-list': 'MyCustomHitsList',
    // ...
  }"
/>
​
transform-items
function
default:"items => items"
Receives the items and is called before displaying them. It returns a new array with the same “shape” as the original. This is helpful when transforming or reordering items. Don’t use transformItems to remove items since this will affect your pagination.The entire results data is also available, including all regular response parameters and helper parameters (for example, disjunctiveFacetsRefinements).If you’re transforming an attribute with the ais-highlight widget, you must transform item._highlightResult[attribute].value.
To prevent creating infinite loops, avoid passing arrays, objects, or functions directly in the template. These values aren’t referentially equal on each render, which causes the widget to re-register every time. Instead, define them in your component’s data option and reference them in the template.
Vue
<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.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. 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.
  • banner: object. The banner data returned within the renderingContent property from the Algolia API response.
  • sendEvent: (eventType, hit, eventName) => void. The function to send click or conversion events. The view event is automatically sent when this connector renders hits. Learn more about these events in the insights middleware documentation.
    • 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 found in the search response when 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 object IDs:
        • index by default is the name of the index that returned the passed object IDs.
        • queryID by default is the ID of the query that returned the passed object IDs.
        • positions by default is the absolute position of the passed object IDs.
For more details about the payload property, see the Insights client documentation.
<ais-hits>
  <template v-slot="{ items, banner, sendEvent }">
    <img :src="banner.image.urls[0].url" alt="banner alt text" />
    <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>
​
banner
The slot to override the DOM output of the banner.Scope
  • banner: object. The banner data returned within the renderingContent property from the Algolia API response.
Vue
<ais-hits>
  <template v-slot:banner="{ banner }">
    <img :src="banner.image.urls[0].url" alt="banner alt text" />
  </template>
</ais-hits>
​
item
The slot to override the DOM output of the item.Scope
  • item: object. A single hit with all its attributes.
  • index: number. The relative position of the hit in the list.
Vue
<ais-hits>
  <template v-slot:item="{ item, index }">
    {{ index }} - {{ item.name }}
  </template>
</ais-hits>

​
HTML output

HTML
<div class="ais-Hits">
  <aside class="ais-Hits-banner">
    <a class="ais-Hits-banner-link">
      <img class="ais-Hits-banner-image" />
    </a>
  </aside>
  <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>

​
Click and conversion events

If the insights option is true, the ais-hits widget automatically sends a click event with the following “shape” to the Insights API whenever users click a hit.
JSON
{
  "eventType": "click",
  "insightsMethod": "clickedObjectIDsAfterSearch",
  "payload": {
    "eventName": "Hit Clicked"
    // …
  },
  "widgetType": "ais.hits"
}
To customize this event, use the sendEvent function in your item slot and send a custom click event on the root element.
Vue
<ais-hits>
  <template v-slot:item="{ item, sendEvent }">
    <div @click="sendEvent('click', item, 'Product Clicked')">
      <h2>
        <ais-highlight attribute="name" :hit="item" />
      </h2>
      <p>{{ item.description }}</p>
    </div>
  </template>
</ais-hits>
The sendEvent function also accepts an object as a fourth argument to send directly to the Insights API. You can use it, for example, to send special conversion events with a subtype.
Vue
<ais-hits>
  <template v-slot:item="{ item, sendEvent }">
    <div>
      <h2>
        <ais-highlight attribute="name" :hit="item" />
      </h2>
      <p>{{ item.description }}</p>
      <button
        @click="sendEvent('conversion', item, 'Added To Cart', {
          // Special subtype
          eventSubtype: 'addToCart',
          // An array of objects representing each item added to the cart
          objectData: [
            {
              // The discount value for this item, if applicable
              discount: item.discount || 0,
              // The price value for this item (minus the discount)
              price: item.price,
              // How many of these items were added
              quantity: 2,
              // The per-item `queryID` for the query preceding this event
              queryID: item.__queryID,
            },
          ],
          // The total value of all items
          value: item.price * 2,
          // The currency code
          currency: 'USD',
        })"
      >
        Add to cart
      </button>
    </div>
  </template>
</ais-hits>
Use strings to represent monetary values in major currency units (for example, ‘5.45’). This avoids floating-point rounding issues, especially when performing calculations.
See also: Send click and conversion events with Vue InstantSearch
⌘I