Stats

Shows data about the performed search.

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

<Stats
  // Optional parameters
  classNames={object}
  translations={object}
  ...props={ComponentProps<'div'>}
/>

Import

JavaScript

import { Stats } from "react-instantsearch";

See this widget in action

Preview this widget and its behavior.

About this widget

<Stats> is a widget that displays the total number of matching hits and the time it took to get them (time spent in the Algolia server).

You can also create your own UI with useStats.

Examples

JavaScript

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

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

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

Props

classNames · Partial<StatsClassNames>

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 root element of the widget.

JavaScript

<Stats
  // ...
  classNames={{
    root: "MyStats",
  }}
/>;

translations · Partial<StatsTranslations>

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

• rootElementText. The text for the statistics.

JavaScript

<Stats
  // ...
  translations={{
    rootElementText({ nbHits, processingTimeMS, nbSortedHits, areHitsSorted }) {
      return areHitsSorted && nbHits !== nbSortedHits
      ? `${nbSortedHits!.toLocaleString()} relevant results sorted out of ${nbHits.toLocaleString()} found in ${processingTimeMS.toLocaleString()}ms`
      : `${nbHits.toLocaleString()} results found in ${processingTimeMS.toLocaleString()}ms`;
    }
  }}
/>

...props · React.ComponentProps<'div'>

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

JavaScript

<Stats
  // ...
  className="MyCustomStats"
  title="My custom title"
/>;

Hook

React InstantSearch let you create your own UI for the <Stats> widget with useStats. Hooks provide APIs to access the widget state and interact with InstantSearch.

The useStats Hook returns APIs.

Usage

First, create your React component:

JavaScript

import { useStats } from "react-instantsearch";

function CustomStats() {
  const {
    hitsPerPage,
    nbHits,
    areHitsSorted,
    nbSortedHits,
    nbPages,
    page,
    processingTimeMS,
    query,
  } = useStats();

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

Then, render the widget:

JavaScript

<CustomStats />;

APIs

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

hitsPerPage · number

The maximum number of hits returned per page.

nbHits · number

The number of hits matched by the query.

areHitsSorted · boolean

Indicated whether relevant sort is applied to the result.

nbSortedHits · number

The number of sorted hits from relevant sort.

nbPages · number

The number of returned pages. The calculation is based on the total number of hits (nbHits) divided by the number of hits per page (hitsPerPage), rounded up to the nearest integer.

page · number

The position of the current page (zero-based).

processingTimeMS · number

The time the server took to process the request, in milliseconds. This doesn’t include network time.

query · string

The query send to the server.

Example

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

function CustomStats() {
  const { nbHits, processingTimeMS, query } = useStats();

  return (
    <span>
      {nbHits.toLocaleString()} results found in{" "}
      {processingTimeMS.toLocaleString()}ms for <q>{query}</q>.
    </span>
  );
}