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

export const SearchRequest = () => <Tooltip tip="A search request is a single HTTP call to the Algolia Search API that can run one or more search operations. It can include multiple queries, for example, when querying several indices at once.">
    search request
  </Tooltip>;

export const SearchQuery = () => <Tooltip tip="The text users enter into a search box. In the Search API, this corresponds to the query parameter. A search query is often used with filters, facets, and other parameters, but these aren't part of the query text itself.">
    search query
  </Tooltip>;

```ts Signature theme={"system"}
stats({
  container: string | HTMLElement,
  // Optional parameters
  templates?: object,
  cssClasses?: object,
});
```

## Import

<CodeGroup>
  ```js Package manager theme={"system"}
  import { stats } from "instantsearch.js/es/widgets";
  ```

  ```js CDN theme={"system"}
  const { stats } = instantsearch.widgets;
  // or directly use instantsearch.widgets.stats()
  ```
</CodeGroup>

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

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

```js JavaScript icon=code theme={"system"}
stats({
  container: "#stats",
});
```

## Options

<ParamField body="container" type="string | HTMLElement" required>
  The CSS Selector or `HTMLElement` to insert the widget into.

  <CodeGroup>
    ```js string theme={"system"}
    stats({
      container: "#stats",
    });
    ```

    ```js HTMLElement theme={"system"}
    stats({
      container: document.querySelector("#stats"),
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="templates" type="object">
  The [templates](#templates) to use for the widget.

  ```js JavaScript icon=code theme={"system"}
  stats({
    // ...
    templates: {
      // ...
    },
  });
  ```
</ParamField>

<ParamField body="cssClasses" type="object" default="{}">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#style-your-widgets):

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

  ```js JavaScript icon=code theme={"system"}
  stats({
    // ...
    cssClasses: {
      root: "MyCustomStats",
      text: ["MyCustomStatsText", "MyCustomStatsText--subclass"],
    },
  });
  ```
</ParamField>

## 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
This function safely renders templates as HTML strings and works directly in the browser—no build step required.
For details, see [Templating your UI](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js/#templating-your-ui).

<Note>
  The `html` function is available in InstantSearch.js version 4.46.0 or later.
</Note>

<ParamField body="text" type="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 <SearchQuery />.
  * `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 <SearchRequest />, 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.

  <CodeGroup>
    ```js function theme={"system"}
    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>`;
        },
      },
    });
    ```

    ```js string theme={"system"}
    // 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
        `,
      },
    });
    ```
  </CodeGroup>
</ParamField>

## HTML output

```html HTML icon=code-xml theme={"system"}
<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.

<CodeGroup>
  ```js Package manager theme={"system"}
  import { connectStats } from "instantsearch.js/es/connectors";
  ```

  ```js CDN theme={"system"}
  const { connectStats } = instantsearch.connectors;
  // or directly use instantsearch.connectors.connectStats()
  ```
</CodeGroup>

Then it's a 3-step process:

```js JavaScript icon=code theme={"system"}
// 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).

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

<ParamField body="hitsPerPage" type="number">
  The maximum number of hits returned per page.

  ```js JavaScript icon=code theme={"system"}
  const renderStats = (renderOptions, isFirstRender) => {
    const { hitsPerPage } = renderOptions;

    document.querySelector("#stats").innerHTML = `
      <p>${hitsPerPage} hits per page</p>
    `;
  };
  ```
</ParamField>

<ParamField body="nbHits" type="number">
  The number of hits matched by the query.

  ```js JavaScript icon=code theme={"system"}
  const renderStats = (renderOptions, isFirstRender) => {
    const { nbHits } = renderOptions;

    document.querySelector("#stats").innerHTML = `
      <p>${nbHits} hits</p>
    `;
  };
  ```
</ParamField>

<ParamField body="areHitsSorted" type="boolean">
  Indicates whether relevant sort is applied to the result.

  ```js JavaScript icon=code theme={"system"}
  const renderStats = (renderOptions, isFirstRender) => {
    const { areHitsSorted } = renderOptions;

    document.querySelector("#stats").innerHTML = `
      <p>You're seeing ${areHitsSorted ? "relevant" : "all"} results.</p>
    `;
  };
  ```
</ParamField>

<ParamField body="nbSortedHits" type="number">
  The number of sorted hits from relevant sort.

  ```js JavaScript icon=code theme={"system"}
  const renderStats = (renderOptions, isFirstRender) => {
    const { nbSortedHits, nbHits } = renderOptions;

    document.querySelector("#stats").innerHTML = `
      <p>${nbSortedHits} relevant hit(s) sorted out of ${nbHits}</p>
    `;
  };
  ```
</ParamField>

<ParamField body="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.

  ```js JavaScript icon=code theme={"system"}
  const renderStats = (renderOptions, isFirstRender) => {
    const { nbPages } = renderOptions;

    document.querySelector("#stats").innerHTML = `
      <p>${nbPages} pages</p>
    `;
  };
  ```
</ParamField>

<ParamField body="page" type="number">
  The position of the current page (zero-based).

  ```js JavaScript icon=code theme={"system"}
  const renderStats = (renderOptions, isFirstRender) => {
    const { page, nbPages } = renderOptions;

    document.querySelector("#stats").innerHTML = `
      <p>${page + 1}/${nbPages} pages</p>
    `;
  };
  ```
</ParamField>

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

  ```js JavaScript icon=code theme={"system"}
  const renderStats = (renderOptions, isFirstRender) => {
    const { processingTimeMS } = renderOptions;

    document.querySelector("#stats").innerHTML = `
      <p>Results found in ${processingTimeMS}ms</p>
    `;
  };
  ```
</ParamField>

<ParamField body="query" type="string">
  The query sent to the server.

  ```js JavaScript icon=code theme={"system"}
  const renderStats = (renderOptions, isFirstRender) => {
    const { query } = renderOptions;

    document.querySelector("#stats").innerHTML = `
      <q>${query}</q>
    `;
  };
  ```
</ParamField>

<ParamField body="widgetParams" type="object">
  All original widget options forwarded to the render function.

  ```js JavaScript icon=code theme={"system"}
  const renderStats = (renderOptions, isFirstRender) => {
    const { widgetParams } = renderOptions;

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

  // ...

  search.addWidgets([
    customStats({
      container: document.querySelector("#stats"),
    }),
  ]);
  ```
</ParamField>

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

```js JavaScript icon=code theme={"system"}
const customStats = connectStats(renderStats);

search.addWidgets([customStats()]);
```

### Full example

<CodeGroup>
  ```html HTML theme={"system"}
  <div id="stats"></div>
  ```

  ```js JavaScript theme={"system"}
  // 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"),
    }),
  ]);
  ```
</CodeGroup>