stats

Signature

stats({
  container: string | HTMLElement,
  // Optional parameters
  templates?: object,
  cssClasses?: object,
});

Import

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

const { stats } = instantsearch.widgets;
// or directly use instantsearch.widgets.stats()

See this widget in action

Preview this widget and its behavior.

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",
});

stats({
  container: document.querySelector("#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:

hitsPerPage: number. The maximum number of hits returned per page.
nbPages: number. The number of pages returned. 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.
nbHits: number. The number of hits matched by the .
areHitsSorted: boolean. True if the index is currently using relevant sort and displaying only sorted hits.
nbSortedHits: number. The number of sorted hits matched by the query (when using relevant sort).
page: number. The index of the current page (zero-based).
processingTimeMS: number. The time the server took to process the , in milliseconds. This doesn’t include network time.
query: string. The query text.

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.
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>`;
    },
  },
});

// String-based templates are deprecated, use functions instead.
stats({
  // ...
  templates: {
    text: `
      {{#areHitsSorted}}
        {{#hasNoSortedResults}}No relevant results{{/hasNoSortedResults}}
        {{#hasOneSortedResults}}1 relevant result{{/hasOneSortedResults}}
        {{#hasManySortedResults}}{{#helpers.formatNumber}}{{nbSortedHits}}{{/helpers.formatNumber}} relevant results{{/hasManySortedResults}}
        sorted out of {{#helpers.formatNumber}}{{nbHits}}{{/helpers.formatNumber}}
      {{/areHitsSorted}}
      {{^areHitsSorted}}
        {{#hasNoResults}}No results{{/hasNoResults}}
        {{#hasOneResult}}1 result{{/hasOneResult}}
        {{#hasManyResults}}{{#helpers.formatNumber}}{{nbHits}}{{/helpers.formatNumber}} results{{/hasManyResults}}
      {{/areHitsSorted}}
      found in {{processingTimeMS}}ms
    `,
  },
});

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";

const { connectStats } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectStats()

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>
  `;
};

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"),
  }),
]);

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>

// Create the render function
const renderStats = (renderOptions, isFirstRender) => {
  const {
    nbHits,
    areHitsSorted,
    nbSortedHits,
    processingTimeMS,
    query,
    widgetParams,
  } = renderOptions;

  if (isFirstRender) {
    return;
  }

  let count = "";

  if (areHitsSorted) {
    if (nbSortedHits > 1) {
      count = `${nbSortedHits} relevant results`;
    } else if (nbSortedHits === 1) {
      count = "1 relevant result";
    } else {
      count = "No relevant result";
    }
    count += ` sorted out of ${nbHits}`;
  } else {
    if (nbHits > 1) {
      count += `${nbHits} results`;
    } else if (nbHits === 1) {
      count += "1 result";
    } else {
      count += "no result";
    }
  }

  widgetParams.container.innerHTML = `
    ${count} found in ${processingTimeMS}ms
    ${query ? `for <q>${query}</q>` : ""}
  `;
};

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

// Instantiate the custom widget
search.addWidgets([
  customStats({
    container: document.querySelector("#stats"),
  }),
]);

InstantSearch.js

Import

See this widget in action

About this widget

Examples

Options

Templates

HTML output

Customize the UI with `connectStats`

Create a render function

Rendering options

Create and instantiate the custom widget

Full example

​Import

See this widget in action

​About this widget

​Examples

​Options

​Templates

​HTML output

​Customize the UI with connectStats

​Create a render function

​Rendering options

​Create and instantiate the custom widget

​Full example

Import

About this widget

Examples

Options

Templates

HTML output

Customize the UI with `connectStats`

Create a render function

Rendering options

Create and instantiate the custom widget

Full example