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

# Stats

> Shows data about the performed search.

<div className="not-prose algolia-flavor-switcher">
  <div className="afs-dropdown">
    <div className="afs-trigger" role="button" tabIndex="0" aria-haspopup="listbox">
      <span className="afs-current">React</span>

      <svg className="afs-chevron lucide lucide-chevron-down" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
        <path d="m6 9 6 6 6-6" />
      </svg>
    </div>

    <ul className="afs-menu" role="listbox">
      <li role="option" aria-selected="false"><a className="afs-option" href="/doc/api-reference/widgets/stats/js"><span className="afs-option-name">JavaScript</span><span className="afs-option-lib">InstantSearch.js</span></a></li>
      <li role="option" aria-selected="true"><a className="afs-option is-current" href="/doc/api-reference/widgets/stats/react"><span className="afs-option-name">React</span><span className="afs-option-lib">React InstantSearch</span></a></li>
      <li role="option" aria-selected="false"><a className="afs-option" href="/doc/api-reference/widgets/stats/vue"><span className="afs-option-name">Vue</span><span className="afs-option-lib">Vue InstantSearch</span></a></li>
      <li role="option" aria-selected="false"><a className="afs-option" href="/doc/api-reference/widgets/stats/ios"><span className="afs-option-name">iOS</span><span className="afs-option-lib">InstantSearch iOS</span></a></li>
      <li role="option" aria-selected="false"><a className="afs-option" href="/doc/api-reference/widgets/stats/android"><span className="afs-option-name">Android</span><span className="afs-option-lib">InstantSearch Android</span></a></li>
      <li role="option" aria-selected="false"><a className="afs-option" href="/doc/api-reference/widgets/stats/flutter"><span className="afs-option-name">Flutter</span><span className="afs-option-lib">Algolia for Flutter</span></a></li>
    </ul>
  </div>
</div>

<Note>
  This is the **React InstantSearch v7** documentation.
  If you're upgrading from v6, see the [upgrade guide](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-v6-to-react-instantsearch-v7).
  If you were using React InstantSearch Hooks,
  this v7 documentation applies—just check for [necessary changes](/doc/guides/building-search-ui/upgrade-guides/react/#migrate-from-react-instantsearch-hooks-to-react-instantsearch-v7).
  To continue using v6, you can find the [archived documentation](https://algolia.com/old-docs/deprecated/instantsearch/react/v6/api-reference/instantsearch/).
</Note>

```tsx Signature theme={"system"}
<Stats
  // Optional parameters
  classNames={object}
  translations={object}
  ...props={ComponentProps<'div'>}
/>
```

## Import

```jsx JavaScript icon=code theme={"system"}
import { Stats } from "react-instantsearch";
```

<Card title="See this widget in action" icon="monitor-play" href="https://instantsearchjs.netlify.app/stories/?path=/story/metadata-stats--default" horizontal>
  Preview this widget and its behavior.
</Card>

## 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).

<Tip>You can also create your own UI with [`useStats`](#hook).</Tip>

## Examples

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

<ParamField body="classNames" type="Partial<StatsClassNames>">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/react#style-your-widgets) and pass to the widget's elements.
  It's useful to style widgets with class-based CSS frameworks like [Bootstrap](https://getbootstrap.com) or [Tailwind CSS](https://tailwindcss.com).

  * `root`. The root element of the widget.

  ```jsx JavaScript icon=code theme={"system"}
  <Stats
    // ...
    classNames={{
      root: "MyStats",
    }}
  />;
  ```
</ParamField>

<ParamField body="translations" type="Partial<StatsTranslations>">
  A dictionary of translations to customize the UI text and support internationalization.

  * `rootElementText`. The text for the statistics.

  ```jsx JavaScript icon=code theme={"system"}
  <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`;
      }
    }}
  />
  ```
</ParamField>

<ParamField body="...props" type="React.ComponentProps<'div'>">
  Any `<div>` prop to forward to the root element of the widget.

  ```jsx JavaScript icon=code theme={"system"}
  <Stats
    // ...
    className="MyCustomStats"
    title="My custom title"
  />;
  ```
</ParamField>

## 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](#hook).

### Usage

First, create your React component:

```jsx JavaScript icon=code theme={"system"}
import { useStats } from "react-instantsearch";

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

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

Then, render the widget:

```jsx JavaScript icon=code theme={"system"}
<CustomStats />;
```

### APIs

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

<ResponseField name="hitsPerPage" type="number">
  The maximum number of hits returned per page.
</ResponseField>

<ResponseField name="nbHits" type="number">
  The number of hits matched by the query.
</ResponseField>

<ResponseField name="areHitsSorted" type="boolean">
  Indicated whether relevant sort is applied to the result.
</ResponseField>

<ResponseField name="nbSortedHits" type="number">
  The number of sorted hits from relevant sort.
</ResponseField>

<ResponseField name="nbPages" type="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.
</ResponseField>

<ResponseField name="page" type="number">
  The position of the current page (zero-based).
</ResponseField>

<ResponseField name="processingTimeMS" type="number">
  The time the server took to process the request, in milliseconds. This doesn't include network time.
</ResponseField>

<ResponseField name="query" type="string">
  The query send to the server.
</ResponseField>

### Example

```tsx theme={"system"}
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>
  );
}
```
