Skip to main content
Signature
stats({
  container: string | HTMLElement,
  // Optional parameters
  templates?: object,
  cssClasses?: object,
});

​
Import

import { stats } from "instantsearch.js/es/widgets";
View demo

​
About this widget

The stats widget displays the total number of matching hits and the time it took to get them (time spent in the Algolia server).

​
Examples

JavaScript
stats({
  container: "#stats",
});

​
Options

​
container
string | HTMLElement
required
The CSS Selector or HTMLElement to insert the widget into.
stats({
  container: "#stats",
});
​
templates
object
The templates to use for the widget.
JavaScript
stats({
  // ...
  templates: {
    // ...
  },
});
​
cssClasses
object
default:"{}"
The CSS classes you can override:
  • root. The root element of the widget.
  • text. The text element.
JavaScript
stats({
  // ...
  cssClasses: {
    root: "MyCustomStats",
    text: ["MyCustomStatsText", "MyCustomStatsText--subclass"],
  },
});

​
Templates

You can customize parts of a widget’s UI using the Templates API. Each template includes an html function, which you can use as a tagged template. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.
The html function is available in InstantSearch.js version 4.46.0 or later.
​
text
string | function
The template to use to customize the text. It exposes:
  • hasManyResults: boolean. Indicates whether the search has more than one result.
  • hasNoResults: boolean. Indicates whether the search has no results.
  • hasOneResult: boolean. Indicates whether the search has one result.
  • areHitsSorted: boolean. Indicates whether Relevant sort is applied to the result.
  • nbSortedHits: number. The number of sorted hits from Relevant sort.
  • hasManySortedResults: boolean. Indicates whether the search has more than one sorted result.
  • hasNoSortedResults: boolean. Indicates whether the search has no sorted results.
  • hasOneSortedResults: boolean. Indicates whether the search has one sorted result.
  • hitsPerPage: number. Maximum number of hits returned per page.
  • nbHits: number. The number of hits matched by the query.
  • nbPages: 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: 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 sent to the server.
  • cssClasses: object. Same option as the cssClasses parameter provided to the widget.
stats({
  // ...
  templates: {
    text(data, { html }) {
      let count = "";

      if (data.hasManyResults) {
        count += `${data.nbHits} results`;
      } else if (data.hasOneResult) {
        count += `1 result`;
      } else {
        count += `no result`;
      }

      return html`<span>${count} found in ${data.processingTimeMS}ms</span>`;
    },
  },
});

​
HTML output

HTML
<div class="ais-Stats">
  <span class="ais-Stats-text"
    >7,435 relevant results sorted out of 20,337 found in 1ms.</span
  >
</div>

<!-- or -->

<div class="ais-Stats">
  <span class="ais-Stats-text">20,337 results found in 1ms.</span>
</div>

​
Customize the UI with connectStats

If you want to create your own UI of the stats widget, you can use connectors. To use connectStats, you can import it with the declaration relevant to how you installed InstantSearch.js. 
import { connectStats } from "instantsearch.js/es/connectors";
Then it’s a 3-step process:
JavaScript
// 1. Create a render function
const renderStats = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customStats = connectStats(renderStats);

// 3. Instantiate
search.addWidgets([
  customStats({
    // instance params
  }),
]);

​
Create a render function

This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).
JavaScript
const renderStats = (renderOptions, isFirstRender) => {
  const {
    hitsPerPage,
    nbHits,
    areHitsSorted,
    nbSortedHits,
    nbPages,
    page,
    processingTimeMS,
    query,
    widgetParams,
  } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
};

​
Rendering options

​
hitsPerPage
number
The maximum number of hits returned per page.
JavaScript
const renderStats = (renderOptions, isFirstRender) => {
  const { hitsPerPage } = renderOptions;

  document.querySelector("#stats").innerHTML = `
    <p>${hitsPerPage} hits per page</p>
  `;
};
​
nbHits
number
The number of hits matched by the query.
JavaScript
const renderStats = (renderOptions, isFirstRender) => {
  const { nbHits } = renderOptions;

  document.querySelector("#stats").innerHTML = `
    <p>${nbHits} hits</p>
  `;
};
​
areHitsSorted
boolean
Indicates whether relevant sort is applied to the result.
JavaScript
const renderStats = (renderOptions, isFirstRender) => {
  const { areHitsSorted } = renderOptions;

  document.querySelector("#stats").innerHTML = `
    <p>You're seeing ${areHitsSorted ? "relevant" : "all"} results.</p>
  `;
};
​
nbSortedHits
number
The number of sorted hits from relevant sort.
JavaScript
const renderStats = (renderOptions, isFirstRender) => {
  const { nbSortedHits, nbHits } = renderOptions;

  document.querySelector("#stats").innerHTML = `
    <p>${nbSortedHits} relevant hit(s) sorted out of ${nbHits}</p>
  `;
};
​
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.
JavaScript
const renderStats = (renderOptions, isFirstRender) => {
  const { nbPages } = renderOptions;

  document.querySelector("#stats").innerHTML = `
    <p>${nbPages} pages</p>
  `;
};
​
page
number
The position of the current page (zero-based).
JavaScript
const renderStats = (renderOptions, isFirstRender) => {
  const { page, nbPages } = renderOptions;

  document.querySelector("#stats").innerHTML = `
    <p>${page + 1}/${nbPages} pages</p>
  `;
};
​
processingTimeMS
number
The time the server took to process the request, in milliseconds. This doesn’t include network time.
JavaScript
const renderStats = (renderOptions, isFirstRender) => {
  const { processingTimeMS } = renderOptions;

  document.querySelector("#stats").innerHTML = `
    <p>Results found in ${processingTimeMS}ms</p>
  `;
};
​
query
string
The query sent to the server.
JavaScript
const renderStats = (renderOptions, isFirstRender) => {
  const { query } = renderOptions;

  document.querySelector("#stats").innerHTML = `
    <q>${query}</q>
  `;
};
​
widgetParams
object
All original widget options forwarded to the render function.
JavaScript
const renderStats = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = "...";
};

// ...

search.addWidgets([
  customStats({
    container: document.querySelector("#stats"),
  }),
]);

​
Create and instantiate the custom widget

First, create your custom widgets using a rendering function. Then, instantiate them with parameters. There are two kinds of parameters you can pass:
  • Instance parameters. Predefined options that configure Algolia’s behavior.
  • Custom parameters. Parameters you define to make the widget reusable and adaptable.
Inside the renderFunction, both instance and custom parameters are accessible through connector.widgetParams.
JavaScript
const customStats = connectStats(renderStats);

search.addWidgets([customStats()]);

​
Full example

<div id="stats"></div>
⌘I