StarsRatingBar

Components/Form

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/starsratingbar

Overview

Copy

A star rating bar allows the user to rate the quality of an item or an experience, such as a purchased product, completed service or received meal from a restaurant.

Do

  • Use it to collect feedback about the quality an item or a service.
  • Use it to display the rating of an item or a service.

Don't

  • Don't use it to rate the experience with an item or service on an emotional level, use <FacesRatingBar/> instead

Feature examples

Mode

Specify the mode of component:

  • Interactive (default) - used to collect individual feedback.
  • readOnly - used to display overall rating.
Copy

Size

Control the size of a component:

  • large
  • medium
  • small
  • tiny

Interactive mode, which requires input from the user, supports large and medium sizes only.

Copy

Captions

Give more context to the rating scale by providing value labels.

Captions will be shown only if all 5 labels are defined.

Copy

Status message

Add text that explains the status or what action the user should take with the statusMessage prop.

Show the status message inline, directly below the rating bar by wrapping it in a <FormField/> and adding statusMessage.

View more inline status message examples in <FormField/>.

Copy

Common use case examples

Collecting feedback

Use an interactive rating bar to collect feedback from your users.

Copy

Displaying feedback

Use readOnly mode to display individual or general ratings of an item or service.

Copy

Code

Copy

Props

NameTypeDefaultDescription
dataHookstring—Applies a data-hook HTML attribute that can be used in tests.
descriptionValuesstring[]—Specifies the rate caption value labels. Array must contain all 5 strings to display the rating labels.
labelValuesstring[]—Specifies the rate input value labels.
namestring—Specifies radio group name.
onChange(rating: number) => void—Defines a handler that is called whenever rating changes. ##### Signature: function(rating: number) => void * * rating: 1 | 2 | 3 | 4 | 5
readOnlyboolean—Specifies whether the rating bar is in read-only mode.
refnull | string | (instance: HTMLInputElement | null) => void | RefObject<HTMLInputElement>—Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref).
size"small" | "tiny" | "medium" | "large"—Controls the size of the star rating bar. Interactive mode can be large or medium. The default value for the read only mode is medium.
value (required)number—Specifies the selected rate, from 0 to 5. 0 indicates an undefined rating.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
selectRatingSelects a star rating bar value
getSelectedRatingGets the selected rating (a number between 0 to 5)
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.344.0 (2026-10-28) — maintenance release, no component-specific changes
  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.326.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — fix: unfilled stars now use a dedicated --wds-stars-rating-bar-unfilled-star-color token instead of the shared --wds-color-black-500 primitive directly. In odeditor-dark (Studio 2.0) it resolves to black.400 instead of black.500, fixing insufficient contrast against dark surfaces — most visible for read-only ratings. Every other theme aliases to the unchanged black.500, so nothing else visually changes, including odeditor (Harmony). Other components consuming --wds-color-black-500 directly are unaffected. (#17016) — has visual changes
  • 1.323.0 (2026-09-10) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.299.0 (2026-07-17) — maintenance release, no component-specific changes
  • 1.298.0 (2026-07-14) — breaking: resolve stylable extends warning on readonly variant (#16535) — has visual changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.193.0 (2025-05-30) — maintenance release, no component-specific changes
  • 1.191.2 (2025-05-28) — maintenance release, no component-specific changes
  • 1.186.1 (2025-05-06) — fix: rework accessibility, tokenize (#14791)
  • 1.183.0 (2025-04-24) — maintenance release, no component-specific changes
  • 1.167.0 (2025-03-05) — feat: add interactive mode medium (#14580)
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 30 October 2026

Did this help?