> ## 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 = () =>
search request
;
export const SearchQuery = () =>
search query
;
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
FlavorSwitcher requires at least one option.
;
}
const selected = options.find(option => option.value === current) ?? options[0];
return ;
};
```ts Signature theme={"system"}
stats({
container: string | HTMLElement,
// Optional parameters
templates?: object,
cssClasses?: object,
});
```
## Import
```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()
```
Preview this widget and its behavior.
## 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
The CSS Selector or `HTMLElement` to insert the widget into.
```js string theme={"system"}
stats({
container: "#stats",
});
```
```js HTMLElement theme={"system"}
stats({
container: document.querySelector("#stats"),
});
```
The [templates](#templates) to use for the widget.
```js JavaScript icon=code theme={"system"}
stats({
// ...
templates: {
// ...
},
});
```
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"],
},
});
```
## 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).
The `html` function is available in InstantSearch.js version 4.46.0 or later.
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.
```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`${count} found in ${data.processingTimeMS}ms`;
},
},
});
```
```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
`,
},
});
```
## HTML output
```html HTML icon=code-xml theme={"system"}
7,435 relevant results sorted out of 20,337 found in 1ms.
20,337 results found in 1ms.
```
## 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.
```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()
```
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
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 = `
${hitsPerPage} hits per page
`;
};
```
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 = `
${nbHits} hits
`;
};
```
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 = `
You're seeing ${areHitsSorted ? "relevant" : "all"} results.
`;
};
```
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 = `
${nbSortedHits} relevant hit(s) sorted out of ${nbHits}
`;
};
```
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 = `
${nbPages} pages
`;
};
```
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 = `
${page + 1}/${nbPages} pages
`;
};
```
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 = `
Results found in ${processingTimeMS}ms
`;
};
```
The query sent to the server.
```js JavaScript icon=code theme={"system"}
const renderStats = (renderOptions, isFirstRender) => {
const { query } = renderOptions;
document.querySelector("#stats").innerHTML = `
${query}
`;
};
```
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"),
}),
]);
```
### 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
```html HTML theme={"system"}
```
```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 ${query}
` : ""}
`;
};
// Create the custom widget
const customStats = connectStats(renderStats);
// Instantiate the custom widget
search.addWidgets([
customStats({
container: document.querySelector("#stats"),
}),
]);
```