ratingMenu

Signature

ratingMenu({
  container: string | HTMLElement,
  attribute: string,
  // Optional parameters
  max?: number,
  templates?: object,
  cssClasses?: object,
});

Import

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

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

See this widget in action

Preview this widget and its behavior.

The ratingMenu widget lets users refine search results by clicking on stars. The stars are based on the selected attribute.

Requirements

The attribute provided to the widget must be in attributes for faceting, either on the dashboard or using the 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

JavaScript

ratingMenu({
  container: "#rating-menu",
  attribute: "rating",
});

Options

container

string | HTMLElement

required

The CSS Selector or HTMLElement to insert the widget into.

ratingMenu({
  // ...
  container: "#rating-menu",
});

ratingMenu({
  // ...
  container: document.querySelector("#rating-menu"),
});

attribute

string

required

The name of the attribute in the record.

JavaScript

ratingMenu({
  // ...
  attribute: "rating",
});

max

number

default:5

The maximum value for the rating. This value is exclusive, which means the number of stars will be the provided value, minus one.

JavaScript

ratingMenu({
  // ...
  max: 4,
});

templates

object

The templates to use for the widget.

JavaScript

ratingMenu({
  // ...
  templates: {
    // ...
  },
});

cssClasses

object

default:"{}"

The CSS classes you can override:

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.

JavaScript

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

item

string | function

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

ratingMenu({
  // ...
  templates: {
    item(data, { html }) {
      return html`
        <a
          href="${data.url}"
          class="${data.cssClasses.link}"
          aria-label="${data.name} & up"
        >
          ${data.stars.map(
            (isFilled) => html`
              <svg
                class="${data.cssClasses.starIcon} ${isFilled
                  ? data.cssClasses.fullStarIcon
                  : data.cssClasses.emptyStarIcon}"
                aria-hidden="true"
                width="24"
                height="24"
              >
                <use
                  xlink:href="#${isFilled
                    ? "ais-RatingMenu-starSymbol"
                    : "ais-RatingMenu-starEmptySymbol"}"
                />
              </svg>
            `,
          )}
          <span class="${data.cssClasses.label}">& Up</span>
          <span class="${data.cssClasses.count}">${data.count}</span>
        </a>
      `;
    },
  },
});

// String-based templates are deprecated, use functions instead.
ratingMenu({
  // ...
  templates: {
    item: `
      {{#count}}
        <a class="{{cssClasses.link}}" aria-label="{{value}} & up" href="{{url}}">
      {{/count}}
      {{^count}}
        <div class="{{cssClasses.link}}" aria-label="{{value}} & up" disabled>
      {{/count}}
      {{#stars}}
        <svg
          class="{{cssClasses.starIcon}} {{#.}}{{cssClasses.fullStarIcon}}{{/.}}{{^.}}{{cssClasses.emptyStarIcon}}{{/.}}"
          aria-hidden="true"
          width="24"
          height="24"
        >
          {{#.}}<use xlink:href="#ais-RatingMenu-starSymbol"></use>{{/.}}
          {{^.}}<use xlink:href="#ais-RatingMenu-starEmptySymbol"></use>{{/.}}
        </svg>
      {{/stars}}
      <span class="{{cssClasses.label}}">&amp; Up</span>
      {{#count}}
        <span class="{{cssClasses.count}}">{{#helpers.formatNumber}}{{count}}{{/helpers.formatNumber}}</span>
      {{/count}}
      {{#count}}
        </a>
      {{/count}}
      {{^count}}
        </div>
      {{/count}}
    `,
  },
});

HTML output

HTML

<div class="ais-RatingMenu">
  <svg xmlns="http://www.w3.org/2000/svg" style="display:none;">
    <symbol id="ais-RatingMenu-starSymbol" viewBox="0 0 24 24">
      <path d="M12 .288l2.833 8.718h9.167l-7.417 5.389 2.833 8.718-7.416-5.388-7.417 5.388 2.833-8.718-7.416-5.389h9.167z"/>
    </symbol>
    <symbol id="ais-RatingMenu-starEmptySymbol" viewBox="0 0 24 24">
      <path d="M12 6.76l1.379 4.246h4.465l-3.612 2.625 1.379 4.246-3.611-2.625-3.612 2.625 1.379-4.246-3.612-2.625h4.465l1.38-4.246zm0-6.472l-2.833 8.718h-9.167l7.416 5.389-2.833 8.718 7.417-5.388 7.416 5.388-2.833-8.718 7.417-5.389h-9.167l-2.833-8.718z"/>
    </symbol>
  </svg>
  <ul class="ais-RatingMenu-list">
    <li class="ais-RatingMenu-item ais-RatingMenu-item--disabled">
      <div class="ais-RatingMenu-link" aria-label="5 & up" disabled>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <span class="ais-RatingMenu-label" aria-hidden="true">& Up</span>
        <span class="ais-RatingMenu-count">2,300</span>
      </div>
    </li>
    <li class="ais-RatingMenu-item ais-RatingMenu-item--selected">
      <a class="ais-RatingMenu-link" aria-label="4 & up" href="#">
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--empty" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starEmptySymbol"></use></svg>
        <span class="ais-RatingMenu-label" aria-hidden="true">& Up</span>
        <span class="ais-RatingMenu-count">2,300</span>
      </a>
    </li>
    <li class="ais-RatingMenu-item">
      <a class="ais-RatingMenu-link" aria-label="3 & up" href="#">
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--empty" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starEmptySymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--empty" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starEmptySymbol"></use></svg>
        <span class="ais-RatingMenu-label" aria-hidden="true">& Up</span>
        <span class="ais-RatingMenu-count">1,750</span>
      </a>
    </li>
  </ul>
</div>

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.

import { connectRatingMenu } from "instantsearch.js/es/connectors";

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

Then it’s a 3-step process:

JavaScript

// 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).

JavaScript

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

items

object[]

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

JavaScript

const renderRatingMenu = (renderOptions, isFirstRender) => {
  const { items } = renderOptions;

  document.querySelector("#rating-menu").innerHTML = `
    <ul>
      ${items
        .map(
          (item) =>
            `<li>
              <a href="#">
                ${item.stars.map((isFilled) => (isFilled ? "★" : "☆")).join("")}
                <span>&amp; Up</span>
                <span>${item.count}</span>
              </a>
            </li>`,
        )
        .join("")}
    </ul>
  `;
};

canRefine

boolean

required

Indicates if search state can be refined.

JavaScript

const renderRatingMenu = (renderOptions, isFirstRender) => {
  const { canRefine } = renderOptions;

  if (!canRefine) {
    document.querySelector("#rating-menu").innerHTML = "";
    return;
  }
};

refine

function

Selects a rating to filter the results. Takes the value of an item as parameter.

JavaScript

const renderRatingMenu = (renderOptions, isFirstRender) => {
  const { items, refine } = renderOptions;

  const container = document.querySelector("#rating-menu");

  if (isFirstRender) {
    container.appendChild(document.createElement("ul"));

    return;
  }

  container.querySelector("ul").innerHTML = items
    .map(
      (item) =>
        `<li>
          <a
            href="#"
            data-value="${item.value}"
            style="font-weight: ${item.isRefined ? "bold" : ""}"
          >
            ${item.stars.map((isFilled) => (isFilled ? "★" : "☆")).join("")}
            <span>&amp; Up</span>
            <span>${item.count}</span>
          </a>
        </li>`,
    )
    .join("");

  [...container.querySelectorAll("a")].forEach((element) => {
    element.addEventListener("click", (event) => {
      event.preventDefault();
      refine(event.currentTarget.dataset.value);
    });
  });
};

sendEvent

(eventType, facetValue) => void

The function to send click events. The click event is automatically sent when refine is called. To learn more, see the insights middleware.

eventType: 'click'
facetValue: string

JavaScript

// 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',
  }
*/

createURL

function

Generates a URL for the next state. Takes the value of an item as parameter.

JavaScript

const renderRatingMenu = (renderOptions, isFirstRender) => {
  const { items, createURL } = renderOptions;

  document.querySelector("#rating-menu").innerHTML = `
    <ul>
      ${items
        .map(
          (item) =>
            `<li>
              <a href="${createURL(item.value)}">
                <span>${item.name} &amp; Up</span>
                <span>${item.count}</span>
              </a>
            </li>`,
        )
        .join("")}
    </ul>
  `;
};

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 customRatingMenu = connectRatingMenu(renderRatingMenu);

search.addWidgets([
  customRatingMenu({
    attribute,
    // Optional parameters
    max,
  }),
]);

Instance options

attribute

string

required

The name of the attribute in the record.

JavaScript

customRatingMenu({
  attribute: "rating",
});

max

number

default:5

The maximum value for the rating.

JavaScript

customRatingMenu({
  // ...
  max: 4,
});

Full example

<div id="rating-menu"></div>

// 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) =>
        `<li>
          <a
            href="${createURL(item.value)}"
            data-value="${item.value}"
            style="font-weight: ${item.isRefined ? "bold" : ""}"
          >
            ${item.stars.map((isFilled) => (isFilled ? "★" : "☆")).join("")}
            <span>&amp; Up</span>
            <span>${item.count}</span>
          </a>
        </li>`,
    )
    .join("");

  [...widgetParams.container.querySelectorAll("a")].forEach((element) => {
    element.addEventListener("click", (event) => {
      event.preventDefault();
      refine(event.currentTarget.dataset.value);
    });
  });
};

// Create the custom widget
const customRatingMenu = connectRatingMenu(renderRatingMenu);

// Instantiate the custom widget
search.addWidgets([
  customRatingMenu({
    container: document.querySelector("#rating-menu"),
    attribute: "rating",
  }),
]);

InstantSearch.js

Import

See this widget in action

About this widget

Requirements

Examples

Options

Templates

HTML output

Customize the UI with `connectRatingMenu`

Create a render function

Render options

Create and instantiate the custom widget

Instance options

Full example

​Import

See this widget in action

​About this widget

​Requirements

​Examples

​Options

​Templates

​HTML output

​Customize the UI with connectRatingMenu

​Create a render function

​Render options

​Create and instantiate the custom widget

​Instance options

​Full example

Import

About this widget

Requirements

Examples

Options

Templates

HTML output

Customize the UI with `connectRatingMenu`

Create a render function

Render options

Create and instantiate the custom widget

Instance options

Full example