> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ais-hits

> Shows a list of search results.

export const Records = () => <Tooltip tip="A record is a searchable object in an Algolia index. Each record consists of named attributes." cta="Algolia records" href="/doc/guides/sending-and-managing-data/prepare-your-data#algolia-records">
    records
  </Tooltip>;

export const Index = () => <Tooltip tip="An Algolia index is a searchable dataset that consists of records and configuration settings. These settings define how the records are searched and ranked.">
    index
  </Tooltip>;

```vue Signature theme={"system"}
<ais-hits
  // Optional parameters
  :show-banner="boolean"
  :escapeHTML="boolean"
  :class-names="object"
  :transform-items="function"
/>
```

## Import

<Tabs>
  <Tab title="Component">
    To ensure optimal bundle sizes,
    see [Optimize build size](/doc/guides/building-search-ui/going-further/improve-performance/vue#optimize-build-size).

    ```js Vue icon=code theme={"system"}
    import { AisHits } from "vue-instantsearch";
    // Use "vue-instantsearch/vue3/es" for Vue 3

    export default {
      components: {
        AisHits,
      },
      // ...
    };
    ```
  </Tab>

  <Tab title="Plugin">
    This imports all widgets, even the ones you don't use.
    For more information, see [Get started with Vue InstantSearch](/doc/guides/building-search-ui/getting-started/vue).

    ```js JavaScript icon="code" theme={"system"}
    import Vue from "vue";
    import InstantSearch from "vue-instantsearch";
    // Use "vue-instantsearch/vue3/es" for Vue 3

    Vue.use(InstantSearch);
    ```
  </Tab>
</Tabs>

<Card title="See this widget in action" icon="monitor-play" href="https://instantsearchjs.netlify.app/stories/vue/?selectedKind=ais-hits" horizontal>
  Preview this widget and its behavior.
</Card>

## 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`](/doc/api-reference/widgets/hits-per-page/vue)
or [`ais-configure`](/doc/api-reference/widgets/configure/vue) widget.

See also:

* [Structured results](/doc/guides/building-search-ui/ui-and-ux-patterns/structured-results/vue)
* [Multi-index search](/doc/guides/building-search-ui/ui-and-ux-patterns/multi-index-search/vue)
* [Searches without results](/doc/guides/building-search-ui/going-further/conditional-display/vue#handling-no-results)

## Examples

```vue Vue icon=code theme={"system"}
<ais-hits />
```

## Props

<ParamField body="show-banner" type="boolean" default={true}>
  Whether to display a top banner when banner data is included within the `renderingContent` property from the Algolia API response.

  ```vue Vue icon=code theme={"system"}
  <ais-hits :show-banner="true" />
  ```
</ParamField>

<ParamField body="escapeHTML" type="boolean" default={true}>
  Whether to escape HTML entities from hits string values.

  ```vue Vue icon=code theme={"system"}
  <ais-hits :escapeHTML="false" />
  ```
</ParamField>

<ParamField body="class-names" type="object" default="{}">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/vue#style-your-widgets):

  * `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 Vue icon=code theme={"system"}
  <ais-hits
    :class-names="{
      'ais-Hits': 'MyCustomHits',
      'ais-Hits-list': 'MyCustomHitsList',
      // ...
    }"
  />
  ```
</ParamField>

<ParamField body="transform-items" type="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](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response) and [helper parameters](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters) (for example, `disjunctiveFacetsRefinements`).

  If you're transforming an attribute with the [`ais-highlight`](/doc/api-reference/widgets/highlight/vue) widget, you must transform `item._highlightResult[attribute].value`.

  <Note>
    To [prevent creating infinite loops](https://support.algolia.com/hc/en-us/articles/4406511683217-Vue-InstantSearch-How-do-I-prevent-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.
  </Note>

  ```vue Vue icon=code theme={"system"}
  <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>

  ```
</ParamField>

## Customize the UI

<ParamField body="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`](/doc/api-reference/widgets/insights/vue) 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 `objectID`s.
      * `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.

  <Note>
    For more details about the `payload` property, see the [Insights client documentation](/doc/libraries/search-insights).
  </Note>

  <CodeGroup>
    ```vue items theme={"system"}
    <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>
    ```

    ```vue insights theme={"system"}
    <ais-hits>
      <template v-slot="{ items, insights }">
        <ul>
          <li v-for="item in items" :key="item.objectID">
            <h1>{{item.name}}</h1>
            <button
              @click="insights(
                'clickedObjectIDsAfterSearch',
                { eventName: 'Add to cart', objectIDs: [item.objectID] }
              )"
            >
              Add to cart
            </button>
          </li>
        </ul>
      </template>
    </ais-hits>
    ```
  </CodeGroup>
</ParamField>

<ParamField body="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 Vue icon=code theme={"system"}
  <ais-hits>
    <template v-slot:banner="{ banner }">
      <img :src="banner.image.urls[0].url" alt="banner alt text" />
    </template>
  </ais-hits>
  ```
</ParamField>

<ParamField body="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 Vue icon=code theme={"system"}
  <ais-hits>
    <template v-slot:item="{ item, index }">
      {{ index }} - {{ item.name }}
    </template>
  </ais-hits>
  ```
</ParamField>

## HTML output

```html HTML icon=code-xml theme={"system"}
<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`](/doc/api-reference/widgets/instantsearch/vue#param-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 JSON icon=braces theme={"system"}
{
  "eventType": "click",
  "insightsMethod": "clickedObjectIDsAfterSearch",
  "payload": {
    "eventName": "Hit Clicked"
    // …
  },
  "widgetType": "ais.hits"
}
```

To customize this event, use the `sendEvent` function in your [`item`](#param-item) slot and send a custom `click` event on the root element.

```vue Vue icon=code theme={"system"}
<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 Vue icon=code theme={"system"}
<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>
```

<Note>
  Use strings to represent monetary values in major currency units (for example, '5.45').
  This avoids floating-point rounding issues, especially when performing calculations.
</Note>

See also: [Send click and conversion events with Vue InstantSearch](/doc/guides/building-search-ui/events/vue)