UI libraries / React InstantSearch / Widgets

<Stats>

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch v6, you can find the archived documentation.

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

import { Stats } from 'react-instantsearch';
See code examples
See live example

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

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

import React from 'react';
import 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

Parameter Description
classNames
type: Partial<StatsClassNames>
Optional

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.
Copy 
1
2
3
4
5
6

<Stats
  // ...
  classNames={{
    root: 'MyStats'
  }}
/>
translations
type: Partial<StatsTranslations>
Optional

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

  • rootElementText: The text for the statistics.
Copy 
1
2
3
4
5
6
7
8
9
10

<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
type: React.ComponentProps<'div'>
Optional

Any <div> prop to forward to the root element of the widget.
Copy 
1
2
3
4
5

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

See code examples

Usage

First, create your React component:

import { useStats } from 'react-instantsearch';

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

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

Then, render the widget:

<CustomStats />

APIs

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

Parameter Description
hitsPerPage
type: number

The maximum number of hits returned per page.
nbHits
type: number

The number of hits matched by the query.
areHitsSorted
type: boolean

Indicated whether Relevant sort is applied to the result.
nbSortedHits
type: number

The number of sorted hits from Relevant sort.
nbPages
type: number

The number of returned pages. 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
type: number

The position of the current page (zero-based).
processingTimeMS
type: number

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

The query send to the server.

Example

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

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>
  );
}
Did you find this page helpful?
React InstantSearch v7