> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# ratingMenu
> Lets users refine search results by selecting star ratings.
export const Records = () =>
records
;
```ts Signature theme={"system"}
ratingMenu({
container: string | HTMLElement,
attribute: string,
// Optional parameters
max?: number,
templates?: object,
cssClasses?: object,
});
```
## Import
```js Package manager theme={"system"}
import { ratingMenu } from "instantsearch.js/es/widgets";
```
```js CDN theme={"system"}
const { ratingMenu } = instantsearch.widgets;
// or directly use instantsearch.widgets.ratingMenu()
```
Preview this widget and its behavior.
## About this widget
The `ratingMenu` widget lets users refine search results by clicking on stars.
The stars are based on the selected attribute.
### Requirements
The [`attribute`](#param-attribute) provided to the widget must be in attributes for faceting,
either on the [dashboard](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard) or using the [`attributesForFaceting`](/doc/api-reference/api-parameters/attributesForFaceting) parameter with the API.
**Attribute values must be integers, not strings or floats.**
The widget only returns exact numerical matches.
For example, if a user selects "4 \[stars] & Up",
only return with values such as 4 or 5 are returned—
not those with values like 4.5 or 4.7.
If your attribute is a float, index a new attribute with the rounded integer value to use in this widget.
## Examples
```js JavaScript icon=code theme={"system"}
ratingMenu({
container: "#rating-menu",
attribute: "rating",
});
```
## Options
The CSS Selector or `HTMLElement` to insert the widget into.
```js string theme={"system"}
ratingMenu({
// ...
container: "#rating-menu",
});
```
```js HTMLElement theme={"system"}
ratingMenu({
// ...
container: document.querySelector("#rating-menu"),
});
```
The name of the attribute in the record.
```js JavaScript icon=code theme={"system"}
ratingMenu({
// ...
attribute: "rating",
});
```
The maximum value for the rating.
This value is exclusive, which means the number of stars will be the provided value, minus one.
```js JavaScript icon=code theme={"system"}
ratingMenu({
// ...
max: 4,
});
```
The [templates](#templates) to use for the widget.
```js JavaScript icon=code theme={"system"}
ratingMenu({
// ...
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.
* `noRefinementRoot`. Container class without results.
* `list`. The list of results.
* `item`. The list items.
* `selectedItem`. The selected item in the list.
* `disabledItem`. The disabled item in the list.
* `starIcon`. The default class of each star (when using the default template).
* `fullStarIcon`. The class of each full star (when using the default template).
* `emptyStarIcon`. The class of each empty star (when using the default template).
* `label`. The label of each item.
* `count`. The count of each item.
```js JavaScript icon=code theme={"system"}
ratingMenu({
// ...
cssClasses: {
root: "MyCustomRatingMenu",
list: ["MyCustomRatingMenuList", "MyCustomRatingMenuList--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 used for displaying each item, with:
* `count: number`. The number of results that match this refinement.
* `isRefined: boolean`. Whether the refinement is selected.
* `name: string`. The name corresponding to the number of stars.
* `value: string`. The number of stars with a string form.
* `url: string`. The value of the URL with the applied refinement.
* `labels: object`. The value of the other templates.
* `cssClasses: object`. The CSS classes provided to the widget.
* `stars: boolean[]`. The list of stars to generate with:
* `true`. Represents a filled star
* `false`. Represents an empty star
```js function theme={"system"}
ratingMenu({
// ...
templates: {
item(data, { html }) {
return html`
${data.stars.map(
(isFilled) => html`
`,
)}
& Up${data.count}
`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
ratingMenu({
// ...
templates: {
item: `
{{#count}}
{{/count}}
{{^count}}
```
## Customize the UI with `connectRatingMenu`
If you want to create your own UI of the `ratingMenu` widget, you can use connectors.
To use `connectRatingMenu`, you can import it with the declaration relevant to how you installed InstantSearch.js.
```js Package manager theme={"system"}
import { connectRatingMenu } from "instantsearch.js/es/connectors";
```
```js CDN theme={"system"}
const { connectRatingMenu } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectRatingMenu()
```
Then it's a 3-step process:
```js JavaScript icon=code theme={"system"}
// 1. Create a render function
const renderRatingMenu = (renderOptions, isFirstRender) => {
// Rendering logic
};
// 2. Create the custom widget
const customRatingMenu = connectRatingMenu(renderRatingMenu);
// 3. Instantiate
search.addWidgets([
customRatingMenu({
// 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 renderRatingMenu = (renderOptions, isFirstRender) => {
const { items, canRefine, refine, sendEvent, createURL } = renderOptions;
if (isFirstRender) {
// Do some initial rendering and bind events
}
// Render the widget
};
```
#### Render options
This list of stars to display, with:
* `count: number`. The number of results that match this refinement.
* `isRefined: boolean`. Whether the refinement is selected.
* `name: string`. The name corresponding to the number of stars.
* `value: string`. The number of stars with a string form.
* `stars: boolean[]`. The list of stars to generate with:
* `true`. Represents a filled star
* `false`. Represents an empty star
```js JavaScript icon=code theme={"system"}
const renderRatingMenu = (renderOptions, isFirstRender) => {
const { items } = renderOptions;
document.querySelector("#rating-menu").innerHTML = `
`,
)
.join("");
[...container.querySelectorAll("a")].forEach((element) => {
element.addEventListener("click", (event) => {
event.preventDefault();
refine(event.currentTarget.dataset.value);
});
});
};
```
The function to send `click` events.
The `click` event is automatically sent when `refine` is called.
To learn more, see the [`insights`](/doc/api-reference/widgets/insights/js) middleware.
* `eventType: 'click'`
* `facetValue: string`
```js JavaScript icon=code theme={"system"}
// For example,
sendEvent("click", 3);
/*
A payload like the following will be sent to the `insights` middleware.
{
eventType: 'click',
insightsMethod: 'clickedFilters',
payload: {
eventName: 'Filter Applied',
filters: ['rates>=3'],
index: '',
},
widgetType: 'ais.ratingMenu',
}
*/
```
Generates a URL for the next state.
Takes the value of an item as parameter.
```js JavaScript icon=code theme={"system"}
const renderRatingMenu = (renderOptions, isFirstRender) => {
const { items, createURL } = renderOptions;
document.querySelector("#rating-menu").innerHTML = `
`;
};
```
### 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 customRatingMenu = connectRatingMenu(renderRatingMenu);
search.addWidgets([
customRatingMenu({
attribute,
// Optional parameters
max,
}),
]);
```
#### Instance options
The name of the attribute in the record.
```js JavaScript icon=code theme={"system"}
customRatingMenu({
attribute: "rating",
});
```
The maximum value for the rating.
```js JavaScript icon=code theme={"system"}
customRatingMenu({
// ...
max: 4,
});
```
### Full example
```html HTML theme={"system"}
```
```js JavaScript theme={"system"}
// Create the render function
const renderRatingMenu = (renderOptions, isFirstRender) => {
const { items, refine, createURL, widgetParams } = renderOptions;
if (isFirstRender) {
widgetParams.container.appendChild(document.createElement("ul"));
return;
}
widgetParams.container.querySelector("ul").innerHTML = items
.map(
(item) =>
`