RatingFacet

Save PDF

Last Updated: May 5, 2026
5 minute read

MarkLogic Server
Documentation

The RatingFacet widget allows users to filter search results by a minimum or exact rating value. The rating control can be rendered as star icons, thumbs up/down icons, numbered buttons, or a slider. It is typically used for filtering products by customer ratings, content by approval scores, or items by numeric quality scores.

MarkLogic setup

Faceted search requires a range index on the faceted property. A range index can be added to the database configuration with the MarkLogic Admin Interface or with an API.

After an index is added, a faceted constraint must be configured using query options. In this example, the search application returns facets for the /envelope/rating property in the search results. return-facets is set to true so that facet results are returned:

<?xml version="1.0" encoding="UTF-8"?>
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="rating">
    <range collation="" facet="true" type="xs:int">
      <path-index>/envelope/rating</path-index>
      <facet-option>limit=25</facet-option>
    </range>
  </constraint>
  <return-facets>true</return-facets>
</options>

The example code will return this response:

{
  "facets": {
    "rating": {
      "type": "rating",
      "facetValues": [
        {
          "name": "1",
          "count": 5,
          "value": 1
        },
        {
          "name": "2",
          "count": 12,
          "value": 2
        },
        {
          "name": "3",
          "count": 28,
          "value": 3
        },
        {
          "name": "4",
          "count": 45,
          "value": 4
        },
        {
          "name": "5",
          "count": 67,
          "value": 5
        }
      ]
    }
  },
  // ...
}

Example rendering

The RatingFacet widget renders a rating control inside a collapsible panel. By default, five stars are displayed. A user can click a star to set the minimum rating filter (for example, clicking the third star filters for items rated 3 stars and above). The current numeric value and an optional label (e.g., "and up") are shown next to the rating control.

RatingFacet example configuration

In this example configuration, the RatingFacet widget is imported and configured in a React application using the default star display.

import { useContext } from "react";
import './App.css';
import { MarkLogicContext, SearchBox, ResultsSnippet, RatingFacet } from "ml-fasttrack";

function App() {

  const context = useContext(MarkLogicContext);

  const handleSearch = (params) => {
    context.setQtext(params?.q);
  }

  const handleRatingChange = (selections, previousSelections) => {
    previousSelections?.forEach(c => context.removeConstraint(c));
    selections.forEach(c => context.addRangeFacetConstraint(c));
  }

  return (
    <div className="App">
      <div>
        <SearchBox onSearch={handleSearch}/>
      </div>
      <div style={{display: 'flex', flexDirection: 'row'}}>
        <div style={{width: '640px'}}>
          <ResultsSnippet
            results={context.searchResponse.results}
            paginationFooter={true}
          />
        </div>
        <div>
          <RatingFacet
            title="Product Rating"
            name="rating"
            data={context?.searchResponse?.facets?.rating ?? { type: 'rating', facetValues: [] }}
            displayConfig={{ type: 'stars' }}
            minValue={1}
            maxValue={5}
            isMinimumFilter={true}
            valueLabel="and up"
            onChange={handleRatingChange}
            containerStyle={{ width: '320px' }}
          />
        </div>
      </div>
    </div>
  );
}

export default App;

Code explanation

In the RatingFacet example configuration:

The data prop is set to the numeric rating facet from the search response object. The facet values provide count information for each rating level.
The displayConfig prop configures the visual style. Setting type to 'stars' renders a 5-star selector.
When isMinimumFilter is true (the default), selecting a rating applies a GE (greater than or equal to) constraint. Setting it to false applies an EQ (exact match) constraint.
The onChange callback receives the current and previous IRatingFacetConstraint arrays, allowing the application to replace old constraints with new ones.
The valueLabel prop appends descriptive text next to the current rating value (e.g., "3 and up").

See the section Setting and resetting facet widgets.

RatingFacet API

Prop	Type	Description
data	{ type: string; facetValues: { name: string; count: number; value: number; }[]; }	Data object that defines the rating filter values.
name	string	The unique key used to identify this facet. Required if `title` is not provided.
title	string	Title for the collapsible header. If not provided, `name` will be used as the facet key.
subTitle	string	Subtitle for the collapsible header.
containerStyle	CSSProperties	CSS styles applied to the widget container.
onChange	(selection: IRatingFacetConstraint[], previousSelection?: IRatingFacetConstraint[]) => void	Callback function triggered when the rating selection changes. Receives the current and previous constraint arrays.
displayConfig	RatingDisplayConfig	Configuration for the display type and its specific properties. See RatingDisplayConfig. Default: `{ type: 'stars' }`.
minValue	number	The minimum value for the rating range. Default: `1`.
maxValue	number	The maximum value for the rating range. Default: `5`.
step	number	The step increment for rating values. Default: `1`.
label	string	Label text displayed above or next to the rating control.
showValue	boolean	Whether to show the numeric value alongside the rating display. Default: `true`.
valueLabel	string	Text displayed next to the rating value (e.g., `'and up'`).
isMinimumFilter	boolean	When `true`, applies a GE (greater than or equal to) constraint. When `false`, applies an EQ (exact match) constraint. Default: `true`.
resetConfig	({ hide?: boolean; label?: string; ButtonProps?: ButtonProps; onReset?: () => void; })	Applies a Reset button to the bottom of the component.
resetConfig.hide	boolean	Whether to hide the Reset button.
resetConfig.label	string	The Reset button label.
resetConfig.ButtonProps	ButtonProps	KendoReact Button props for the Reset button.
resetConfig.onReset	() => void	Callback function triggered when the user clicks the Reset button.
ref	const facetRef = useRef(null);	A React ref object that can be used to access the underlying component instance. See Setting and resetting facet widgets.

RatingDisplayConfig API

The displayConfig prop uses a discriminated union on type to provide type-specific options for each display style.

Stars display (`type: 'stars'`)

displayConfig={{ type: 'stars', size: 'medium', allowHalf: false, filledColor: '#ffc107' }}

Property	Type	Description
`type`	`'stars'`	Renders star icons.
`size`	`'small' \| 'medium' \| 'large'`	Size of the star icons. Default: `'medium'`.
`showCounts`	`boolean`	Whether to show the document count for each value. Default: `false`.
`allowHalf`	`boolean`	Whether to allow half-star ratings. Default: `false`.
`filledIcon`	`ReactNode`	Custom icon for filled stars.
`emptyIcon`	`ReactNode`	Custom icon for empty stars.
`filledColor`	`string`	Color of filled star icons. Default: `'#ffc107'`.
`emptyColor`	`string`	Color of empty star icons. Default: `'#e0e0e0'`.

Thumbs display (`type: 'thumbs'`)

displayConfig={{ type: 'thumbs', showCounts: true, likeLabel: 'Upvote', dislikeLabel: 'Downvote' }}

Property	Type	Description
`type`	`'thumbs'`	Renders thumbs up/down icons.
`size`	`'small' \| 'medium' \| 'large'`	Size of the icons. Default: `'medium'`.
`showCounts`	`boolean`	Whether to show the document count for each value. Default: `false`.
`likeColor`	`string`	Color of the thumbs-up icon. Default: `'#4caf50'`.
`dislikeColor`	`string`	Color of the thumbs-down icon. Default: `'#f44336'`.
`likeLabel`	`string`	Label for the thumbs-up button. Default: `'Like'`.
`dislikeLabel`	`string`	Label for the thumbs-down button. Default: `'Dislike'`.

Numbers display (`type: 'numbers'`)

displayConfig={{ type: 'numbers', filledColor: '#1976d2' }}

Property	Type	Description
`type`	`'numbers'`	Renders numbered buttons.
`size`	`'small' \| 'medium' \| 'large'`	Size of the buttons. Default: `'medium'`.
`showCounts`	`boolean`	Whether to show the document count for each value. Default: `false`.
`filledColor`	`string`	Color of selected number buttons. Default: `'#1976d2'`.

Slider display (`type: 'slider'`)

displayConfig={{ type: 'slider', SliderProps: { vertical: true } }}

Property	Type	Description
`type`	`'slider'`	Renders a slider control.
`SliderProps`	`Partial<SliderProps>`	Additional props for the KendoReact Slider component (excluding `value`, `onChange`, `min`, `max`, and `step`). See KendoReact SliderProps.

Develop with FastTrack

RatingFacet

Table of Contents

RatingFacet

MarkLogic setup

Example rendering

RatingFacet example configuration

Code explanation

Setting and resetting the widget

RatingFacet API

RatingDisplayConfig API

Stars display (`type: 'stars'`)

Thumbs display (`type: 'thumbs'`)

Numbers display (`type: 'numbers'`)

Slider display (`type: 'slider'`)

Develop with FastTrack

RatingFacet

MarkLogic setup

Example rendering

RatingFacet example configuration

Code explanation

Setting and resetting the widget

RatingFacet API

RatingDisplayConfig API

Stars display (type: 'stars')

Thumbs display (type: 'thumbs')

Numbers display (type: 'numbers')

Slider display (type: 'slider')

Stars display (`type: 'stars'`)

Thumbs display (`type: 'thumbs'`)

Numbers display (`type: 'numbers'`)

Slider display (`type: 'slider'`)