Skip to main content
The RatingMenu connector provides the logic to build a custom widget that lets users refine search results based on ratings.

Usage

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

const customRatingMenu = connectRatingMenu(
  (renderOptions, isFirstRender) => {
    const { items, refine, widgetParams } = renderOptions;
    const { container } = widgetParams;
    
    container.innerHTML = `
      <ul>
        ${items.map(item => `
          <li>
            <a 
              href="#" 
              data-value="${item.value}"
              style="${item.isRefined ? 'font-weight: bold' : ''}"
            >
              ${item.stars.map((filled, index) => 
                filled ? '★' : '☆'
              ).join('')} & Up (${item.count})
            </a>
          </li>
        `).join('')}
      </ul>
    `;
    
    container.querySelectorAll('a').forEach(link => {
      link.addEventListener('click', (e) => {
        e.preventDefault();
        refine(e.target.dataset.value);
      });
    });
  }
);

search.addWidgets([
  customRatingMenu({
    container: document.querySelector('#rating-menu'),
    attribute: 'rating',
  }),
]);

Connector Options

attribute
string
required
Name of the attribute for faceting (e.g., “rating”).
max
number
default:"5"
The maximum rating value.

Render Options

items
Array<StarRatingItem>
Possible star ratings the user can apply.Each item has:
  • name: Name corresponding to the number of stars
  • label: Human-readable name for the number of stars
  • value: Number of stars as string
  • count: Count of matched results for this number of stars
  • stars: Array of length equal to max rating value with stars to display or not
  • isRefined: Indicates if star rating refinement is applied
refine
(value: string) => void
Selects a rating to filter the results. Takes the value of an item as parameter.
createURL
(value: string) => string
Creates a URL for the next state. Takes the value of an item as parameter.
canRefine
boolean
Indicates if search state can be refined.
hasNoResults
boolean
true if the last search contains no result.
This parameter is deprecated. Use canRefine instead.
sendEvent
function
Sends an event to the Insights middleware.
widgetParams
object
The options passed to the connector.

Build docs developers (and LLMs) love