Skip to main content
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";
View demo

​
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>
  );
}
⌘I