API Reference / React InstantSearch / RatingMenu

RatingMenu

Signature 
<RatingMenu
  attribute={string}
  // Optional parameters
  defaultRefinement={object}
  min={number}
  max={number}
  translations={object}
/>
See code examples
See live example

About this widget

We released React InstantSearch Hooks, a new InstantSearch library for React. We recommend using React InstantSearch Hooks in new projects or upgrading from React InstantSearch.

The RatingMenu lets the user 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 attributesForFaceting with the API.

The attribute values must be integers, not strings nor floats. If your dataset includes float values, the widget returns only exact numerical matches. For example, if a user selects “4 [stars] & Up”, we only return records with values such as 4 or 5, not records with values like 4.5 or 4.7. If your attribute is a float, we recommend indexing a new attribute with the rounded integer value to use in this widget.

Examples

Copy 
1
2
3

import { RatingMenu } from 'react-instantsearch-dom';

<RatingMenu attribute="rating" />

Parameters

attribute
type: string
Required

The name of the attribute in the record.
Copy 
1

<RatingMenu attribute="rating" />
defaultRefinement
type: object
Optional

The default state of the widget containing the min value for the stars.
Copy 
1
2
3
4

<RatingMenu
  // ...
  defaultRefinement={{ min: 2 }}
/>
min
type: number
Optional

The minimum value for the rating. When not provided, the minimum value is automatically computed by Algolia from the data in the index.
Copy 
1
2
3
4

<RatingMenu
  // ...
  min={2}
/>
max
type: number
Optional

The maximum value for the rating. When not provided, the maximum value is automatically computed by Algolia from the data in the index.
Copy 
1
2
3
4

<RatingMenu
  // ...
  max={4}
/>
translations
type: object
Optional

A mapping of keys to translation values.

  • ratingLabel: the label for the value that suffix the list of stars.
Copy 
1
2
3
4
5
6

<RatingMenu
  // ...
  translations={{
    ratingLabel: '& Up',
  }}
/>

HTML output

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

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

If you want to create your own UI of the RatingMenu widget or use another UI library, you can use connectors.

Connectors are higher-order components. They encapsulate the logic for a specific kind of widget and they provide a way to interact with the InstantSearch context.

They have an outer component API that we call exposed props, and they provide some other props to the wrapped components which are called the provided props.

This connector is also used to build other widgets: RangeSlider RangeInput

It’s a 3-step process:

// 1. Create a React component
const RatingMenu = () => {
  // return the DOM output
};

// 2. Connect the component using the connector
const CustomRatingMenu = connectRange(RatingMenu);

// 3. Use your connected widget
<CustomRatingMenu />

See code examples

Create a React component

const RatingMenu = ({
  object currentRefinement,
  number min,
  number max,
  array count,
  function refine,
  function createURL,
}) => {
  // return the DOM output
};

Provided Props

currentRefinement
type: object

Contains the currently applied refinement or the minimum value.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

const RatingMenu = ({ currentRefinement }) => (
  <ul>
    {new Array(4).fill(null).map((_, index) => (
      <li
        key={index}
        style={{ color: currentRefinement.min === 3 - index ? 'gold' : '' }}
      >
        {new Array(3)
          .fill(null)
          .map((__, innerIndex) => (innerIndex < 3 - index ? '★' : '☆'))}
      </li>
    ))}
  </ul>
);
min
type: number

The minimum available value.
Copy 
1
2
3
4
5

const RatingMenu = ({ min }) => (
  <ul>
    <li>The minimum value: {min}</li>
  </ul>
);
max
type: number

The maximum available value.
Copy 
1
2
3
4
5

const RatingMenu = ({ max }) => (
  <ul>
    <li>The maximum value: {max}</li>
  </ul>
);
count
type: array

The array of values associated with their count.
Copy 
1
2
3
4
5
6
7
8
9

const RatingMenu = ({ count }) => (
  <ul>
    {count.map(({ value, count }) => (
      <li key={value}>
        Count for rating value {value}: {count}
      </li>
    ))}
  </ul>
);
refine
type: function

Selects a rating.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

const RatingMenu = ({ currentRefinement, refine }) => (
  <ul>
    {new Array(4).fill(null).map((_, index) => (
      <li key={index}>
        <a
          href="#"
          style={{ color: currentRefinement.min === 3 - index ? 'gold' : '' }}
          onClick={event => {
            event.preventDefault();
            refine({ min: 3 - index });
          }}
        >
          {new Array(3)
            .fill(null)
            .map((__, innerIndex) => (innerIndex < 3 - index ? '★' : '☆'))}
        </a>
      </li>
    ))}
  </ul>
);
createURL
type: function

Generates a URL for the corresponding search state.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

const RatingMenu = ({ currentRefinement, createURL }) => (
  <ul>
    {new Array(4).fill(null).map((_, index) => (
      <li key={index}>
        <a href={createURL({ min: 3 - index })}>
          {new Array(3)
            .fill(null)
            .map((__, innerIndex) => (innerIndex < 3 - index ? '★' : '☆'))}
        </a>
      </li>
    ))}
  </ul>
);

Create and instantiate your connected widget

const CustomRatingMenu = connectRange(RatingMenu);

<CustomRatingMenu
  attribute={string}
  // Optional parameters
  defaultRefinement={object}
  min={number}
  max={number}
/>

Exposed Props

attribute
type: string
Required

The name of the attribute in the record.
Copy 
1

<CustomRatingMenu attribute="rating" />
defaultRefinement
type: object
Optional

The default state of the widget containing the min value for the stars.
Copy 
1
2
3
4

<CustomRatingMenu
  // ...
  defaultRefinement={{ min: 2 }}
/>
min
type: number
Optional

The minimum value for the rating. When not provided, the minimum value is automatically computed by Algolia from the data in the index.
Copy 
1
2
3
4

<CustomRatingMenu
  // ...
  min={2}
/>
max
type: number
Optional

The maximum value for the rating. When not provided, the maximum value is automatically computed by Algolia from the data in the index.
Copy 
1
2
3
4

<CustomRatingMenu
  // ...
  max={4}
/>

Full example

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

import { connectRange } from 'react-instantsearch-dom';

const RatingMenu = ({ currentRefinement, refine }) => (
  <ul>
    {new Array(4).fill(null).map((_, index) => (
      <li key={index}>
        <a
          href="#"
          style={{ color: currentRefinement.min === 3 - index ? 'gold' : '' }}
          onClick={event => {
            event.preventDefault();
            refine({ min: 3 - index });
          }}
        >
          {new Array(3)
            .fill(null)
            .map((__, innerIndex) => (innerIndex < 3 - index ? '★' : '☆'))}
        </a>
      </li>
    ))}
  </ul>
);

const CustomRatingMenu = connectRange(RatingMenu);
Did you find this page helpful?
React InstantSearch v6