InfiniteHits - Algolia

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

Signature

<InfiniteHits
  // Optional props
  hitComponent={({ hit }) => JSX.Element}
  showPrevious={boolean}
  transformItems={function}
  cache={object}
  classNames={object}
  translations={object}
  ...props={ComponentProps<'div'>}
/>

Import

JavaScript

import { InfiniteHits } from "react-instantsearch";

View demo

The <InfiniteHits> widget displays a list of results with a “Show more” button at the bottom of the list. As an alternative to this approach, the infinite scroll guide describes how to create an automatically scrolling infinite hits experience. See also: Searches without results

You can also create your own UI with useInfiniteHits.

Examples

import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, InfiniteHits } from "react-instantsearch";

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function Hit({ hit }) {
  return JSON.stringify(hit);
}

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <InfiniteHits hitComponent={Hit} />
    </InstantSearch>
  );
}

Props

hitComponent

(props: { hit: THit; sendEvent: SendEventForHits }) => JSX.Element

required

A component that renders each hit from the results. It receives a hit and a sendEvent (for insights) prop.When not provided, the widget displays the hit as a JSON string.

JavaScript

<InfiniteHits hitComponent={({ hit }) => hit.objectID} />;

bannerComponent

((props: { banner: SearchResults['renderingContent']['widgets']['banners'][0] }) => JSX.Element) | false

A component that renders the banner data on the renderingContent property from the Algolia response. It overrides the default banner rendering.When false, the widget does not render the banner.

JavaScript

// Override the default banner rendering
<InfiniteHits
  // ...
  bannerComponent={({ banner }) => <img src={banner.image.urls[0].url} />}
/>
// Disable the banner rendering
<InfiniteHits
  // ...
  bannerComponent={false}
/>

showPrevious

boolean

default:true

Enable the button to load previous results.

JavaScript

<InfiniteHits
  // ...
  showPrevious={false}
/>;

escapeHTML

boolean

default:true

Whether to escape HTML tags from hits string values.

JavaScript

<InfiniteHits
  // ...
  escapeHTML={false}
/>;

transformItems

(items: object[], metadata: { results: SearchResults }) => object[]

A function that receives the list of items before they are displayed. It should return a new array with the same structure. Use this to transform, filter, or reorder the items.The function also has access to the full results data, including all standard response parameters and parameters from the helper, such as disjunctiveFacetsRefinements.If you transform an attribute you’re using with the <Highlight> widget, you must also transform the corresponding item._highlightResult[attribute].value.

// Using only items
const transformItems = (items) => {
  return items.map((item) => ({
    ...item,
    label: item.name.toUpperCase(),
  }));
};

// Using items and results
const transformItems = (items, { results }) => {
  return items.map((item, index) => ({
    ...item,
    position: { index, page: results.page },
  }));
};

function Search() {
  return (
    <InfiniteHits
      // ...
      transformItems={transformItems}
    />
  );
}

cache

InfiniteHitsCache

The widget caches all loaded hits. By default, it uses its own internal in-memory cache implementation. Alternatively, use sessionStorage to retain the cache even if users reload the page.You can also implement your own cache object with read and write methods. This can be handy if you need to persist the data across sessions or if you expect the cached data to grow larger than the browser’s 5 MB allowed storage.

import { createInfiniteHitsSessionStorageCache } from "instantsearch.js/es/lib/infiniteHitsCache";

const sessionStorageCache = createInfiniteHitsSessionStorageCache();

<InfiniteHits
  // ...
  cache={sessionStorageCache}
/>;

classNames

Partial<InfiniteHitsClassNames>

The CSS classes you can override and pass to the widget’s elements. It’s useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

root. The widget’s root element.
emptyRoot. The root element without results.
list. The list of results.
item. The list items.
loadPrevious. The “Load previous” button.
disabledLoadPrevious. The “Load previous” button when there are no previous results to load.
loadMore. The “Load more” button.
disabledLoadMore. The “Load more” button when there are no more results to load.
bannerRoot. The root element of the banner.
bannerImage. The image element of the banner.
bannerLink. The anchor element of the banner.

JavaScript

<InfiniteHits
  // ...
  classNames={{
    root: "MyCustomInfiniteHits",
    list: "MyCustomInfiniteHitsList MyCustomInfiniteHitsList--subclass",
  }}
/>;

translations

Partial<InfiniteHitsTranslations>

A dictionary of translations to customize the UI text and support internationalization.

showPreviousButtonText. The text for the “Show previous” button.
showMoreButtonText. The text for the “Show more” button.

JavaScript

<InfiniteHits
  // ...
  translations={{
    showPreviousButtonText: "Load previous results",
    showMoreButtonText: "Load more results",
  }}
/>;

...props

React.ComponentProps<'div'>

Any <div> prop to forward to the widget’s root element.

JavaScript

<InfiniteHits
  // ...
  className="MyCustomInfiniteHits"
  title="My custom title"
/>;

Hook

React InstantSearch let you create your own UI for the <InfiniteHits> widget with useInfiniteHits. Hooks provide APIs to access the widget state and interact with InstantSearch. The useInfiniteHits Hook accepts parameters and returns APIs. It must be used inside the <InstantSearch> component.

Usage

First, create your React component:

JavaScript

import { useInfiniteHits } from "react-instantsearch";

function CustomInfiniteHits(props) {
  const {
    items,
    currentPageHits,
    results,
    banner,
    isFirstPage,
    isLastPage,
    showPrevious,
    showMore,
    sendEvent,
  } = useInfiniteHits(props);

  return <>{/*Your JSX*/}</>;
}

Then, render the widget:

JavaScript

<CustomInfiniteHits {...props} />;

Parameters

Hooks accept parameters. You can either pass them manually or forward props from a custom component.

When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders. Use useCallback() for memoization. Arrays and objects are automatically memoized.

escapeHTML

boolean

default:true

Whether to escape HTML tags from hits string values.

JavaScript

const infiniteHitsApi = useInfiniteHits({
  escapeHTML: false,
});

transformItems

(items: object[], metadata: { results: SearchResults }) => object[]

// Using only items
const transformItems = (items) => {
  return items.map((item) => ({
    ...item,
    label: item.name.toUpperCase(),
  }));
};

// Using items and results
const transformItems = (items, { results }) => {
  return items.map((item, index) => ({
    ...item,
    position: { index, page: results.page },
  }));
};

function InfiniteHits() {
  const infiniteHitsApi = useInfiniteHits({
    // ...
    transformItems,
  });

  return <>{/* Your JSX */}</>;
}

cache

InfiniteHitsCache

The Hook internally caches all loaded hits using its own internal in-memory cache implementation.The library provides another implementation using sessionStorage, which is more persistent and lets you restore the scroll position when you leave and come back to the search page.You can also provide your own implementation by providing a cache object with read and write methods.

import { createInfiniteHitsSessionStorageCache } from "instantsearch.js/es/lib/infiniteHitsCache";

const sessionStorageCache = createInfiniteHitsSessionStorageCache();

const infiniteHitsApi = useInfiniteHits({
  cache: sessionStorageCache,
});

APIs

Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.

items

THit[]

The matched hits returned from Algolia.This returns the combined hits for all the pages that have been requested so far. Use Algolia’s highlighting feature directly from the render function.

currentPageHits

THit[]

The matched hits from Algolia for the current page.Unlike the items parameter, this only returns the hits for the requested page. This can be useful if you want to customize how to add the new page of hits to the existing list.You can use Algolia’s highlighting feature directly from the render function.

results

SearchResults<THit>

The complete response from Algolia.It contains the hits, metadata about the page, the number of hits, and more. Unless you need to access metadata, use items instead.

banner

SearchResults['renderingContent']['widgets']['banners'][0]

The banner data from the renderingContent property in the Algolia response.

isFirstPage

boolean

Whether the first page of hits has been reached.

isLastPage

boolean

Whether the last page of hits has been reached.

showPrevious

() => void

Loads the previous page of hits.

showMore

() => void

Loads the next page of hits.

sendEvent

(eventType: string, hits: Hit | Hits, eventName?: string) => void

The function to send click or conversion events.The view event is automatically sent when this hook renders hits. Check the insights documentation to learn more.

Example

import React from "react";
import { useInfiniteHits } from "react-instantsearch";

function CustomInfiniteHits(props) {
  const { items, sendEvent, showPrevious, showMore, isFirstPage, isLastPage } =
    useInfiniteHits(props);

  return (
    <div>
      <button onClick={showPrevious} disabled={isFirstPage}>
        Show previous results
      </button>
      <ol>
        {items.map((hit) => (
          <li
            key={hit.objectID}
            onClick={() => sendEvent("click", hit, "Hit Clicked")}
            onAuxClick={() => sendEvent("click", hit, "Hit Clicked")}
          >
            <div style={{ wordBreak: "break-all" }}>
              {JSON.stringify(hit).slice(0, 100)}…
            </div>
          </li>
        ))}
      </ol>
      <button onClick={showMore} disabled={isLastPage}>
        Show more results
      </button>
    </div>
  );
}

Click and conversion events

If the insights option is true, the InfiniteHits component 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.infiniteHits"
}

To customize this event, use the sendEvent function in your hitComponent and send a custom click event.

JavaScript

<InfiniteHits
  hitComponent={({ hit, sendEvent }) => (
    <div onClick={() => sendEvent("click", hit, "Product Clicked")}>
      <h2>
        <Highlight attributeName="name" hit={hit} />
      </h2>
      <p>{hit.description}</p>
    </div>
  )}
/>;

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.

JavaScript

<InfiniteHits
  hitComponent={({ hit, sendEvent }) => (
    <div>
      <h2>
        <Highlight attributeName="name" hit={hit} />
      </h2>
      <p>{hit.description}</p>
      <button
        onClick={() =>
          sendEvent("conversion", hit, "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: hit.discount || 0,
                // The price value for this item (minus the discount)
                price: hit.price,
                // How many of this item were added
                quantity: 2,
              },
            ],
            // The total value of all items
            value: hit.price * 2,
            // The currency code
            currency: "USD",
          })
        }
      >
        Add to cart
      </button>
    </div>
  )}
/>;

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

React InstantSearch

​Import

​About this widget

​Examples

​Props

​Hook

​Usage

​Parameters

​APIs

​Example

​Click and conversion events

Import

About this widget

Examples

Props

Hook

Usage

Parameters

APIs

Example

Click and conversion events