Skip to main content
The useStats hook provides the logic to build a custom widget that displays search statistics such as the number of hits and processing time.

​
Import

import { useStats } from 'react-instantsearch';

​
Parameters

This hook does not accept any parameters.

​
Returns

​
nbHits
number
The number of hits in the result set.
const { nbHits } = useStats();
console.log(nbHits); // 1234
​
nbSortedHits
number | undefined
The number of sorted hits in the result set (when using Relevant sort).
const { nbSortedHits } = useStats();
if (nbSortedHits) {
  console.log(`Showing ${nbSortedHits} relevant results`);
}
​
areHitsSorted
boolean
Whether the index is currently using Relevant sort and displaying only sorted hits.
const { areHitsSorted } = useStats();
if (areHitsSorted) {
  console.log('Results are sorted by relevance');
}
​
nbPages
number
The number of pages computed for the result set.
const { nbPages } = useStats();
console.log(`Total pages: ${nbPages}`);
​
page
number
The current page (zero-indexed).
const { page } = useStats();
console.log(`Current page: ${page + 1}`);
​
processingTimeMS
number
The time taken to compute the results inside the Algolia engine (in milliseconds).
const { processingTimeMS } = useStats();
console.log(`Search took ${processingTimeMS}ms`);
​
hitsPerPage
number | undefined
The maximum number of hits per page returned by Algolia.
const { hitsPerPage } = useStats();
console.log(`Showing ${hitsPerPage} items per page`);
​
query
string
The query used for the current search.
const { query } = useStats();
console.log(`Search query: "${query}"`);

​
Examples

​
Basic Stats Display

import { useStats } from 'react-instantsearch';

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

  return (
    <div>
      <strong>{nbHits.toLocaleString()}</strong> results found in{' '}
      <strong>{processingTimeMS}ms</strong>
    </div>
  );
}

​
With Query Display

import { useStats } from 'react-instantsearch';

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

  return (
    <div className="search-stats">
      {query ? (
        <p>
          <strong>{nbHits.toLocaleString()}</strong> results for{' '}
          <em>"{query}"</em> in {processingTimeMS}ms
        </p>
      ) : (
        <p>
          <strong>{nbHits.toLocaleString()}</strong> results in{' '}
          {processingTimeMS}ms
        </p>
      )}
    </div>
  );
}

​
Pagination Stats

import { useStats } from 'react-instantsearch';

function PaginationStats() {
  const { page, nbPages, hitsPerPage, nbHits } = useStats();

  const startResult = page * (hitsPerPage || 0) + 1;
  const endResult = Math.min((page + 1) * (hitsPerPage || 0), nbHits);

  return (
    <div>
      Showing {startResult}-{endResult} of {nbHits.toLocaleString()} results
      (page {page + 1} of {nbPages})
    </div>
  );
}

​
Detailed Stats Panel

import { useStats } from 'react-instantsearch';

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

  return (
    <div className="detailed-stats">
      <h3>Search Statistics</h3>
      <dl>
        <dt>Query:</dt>
        <dd>{query || '(empty)'}</dd>

        <dt>Total Results:</dt>
        <dd>{nbHits.toLocaleString()}</dd>

        {areHitsSorted && nbSortedHits && (
          <>
            <dt>Relevant Results:</dt>
            <dd>{nbSortedHits.toLocaleString()}</dd>
          </>
        )}

        <dt>Processing Time:</dt>
        <dd>{processingTimeMS}ms</dd>

        <dt>Current Page:</dt>
        <dd>
          {page + 1} of {nbPages}
        </dd>

        <dt>Results per Page:</dt>
        <dd>{hitsPerPage}</dd>
      </dl>
    </div>
  );
}

​
Compact Stats

import { useStats } from 'react-instantsearch';

function CompactStats() {
  const { nbHits } = useStats();

  return (
    <span className="compact-stats">
      {nbHits.toLocaleString()} {nbHits === 1 ? 'result' : 'results'}
    </span>
  );
}

​
No Results Message

import { useStats } from 'react-instantsearch';

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

  if (nbHits > 0) {
    return null;
  }

  return (
    <div className="no-results">
      <h3>No results found</h3>
      {query && (
        <p>
          Your search for <strong>"{query}"</strong> did not match any
          products.
        </p>
      )}
      <p>Try different or more general keywords.</p>
    </div>
  );
}

​
Performance Indicator

import { useStats } from 'react-instantsearch';

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

  const getPerformanceLevel = (ms) => {
    if (ms < 100) return { label: 'Fast', color: 'green' };
    if (ms < 500) return { label: 'Normal', color: 'orange' };
    return { label: 'Slow', color: 'red' };
  };

  const performance = getPerformanceLevel(processingTimeMS);

  return (
    <div className="performance">
      <span>{nbHits.toLocaleString()} results</span>
      <span style={{ color: performance.color }}>
        {processingTimeMS}ms ({performance.label})
      </span>
    </div>
  );
}

​
TypeScript

import { useStats } from 'react-instantsearch';

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

  return (
    <div>
      {nbHits} results for "{query}" in {processingTimeMS}ms
    </div>
  );
}