> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: StarsRatingBar Component

## Article: StarsRatingBar Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/form/stars-rating-bar-component.md

## Article Content:

# StarsRatingBar

_Components/Form_

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

## Overview

```jsx
() => {
  const descriptionValues = ['Very bad', 'Bad', 'Ok', 'Good', 'Very good'];
  const [value, setValue] = React.useState(4);

  return (
    <Box align="center">
      <StarsRatingBar
        value={value}
        onChange={setValue}
        descriptionValues={descriptionValues}
      />
    </Box>
  );
};
```

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.

```jsx
() => {
  const [value, setValue] = React.useState(3);

  return (
    <StorybookComponents.Stack>
      <StarsRatingBar value={value} onChange={setValue} />
      <StarsRatingBar value={3} readOnly />
    </StorybookComponents.Stack>
  );
};
```

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

```jsx
<StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column">
    <StarsRatingBar value={0} size="large" />
    <StarsRatingBar value={0} size="medium" />
  </StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column">
    <StarsRatingBar value={0} size="large" readOnly />
    <StarsRatingBar value={0} size="medium" readOnly />
    <StarsRatingBar value={0} size="small" readOnly />
    <StarsRatingBar value={0} size="tiny" readOnly />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Captions

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

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

```jsx
() => {
  const descriptionValues = ['Very bad', 'Bad', 'Ok', 'Good', 'Very good'];

  return (
    <StorybookComponents.Stack flexDirection="column">
      <StarsRatingBar descriptionValues={descriptionValues} value={1} />
      <StarsRatingBar descriptionValues={descriptionValues} value={2} />
      <StarsRatingBar descriptionValues={descriptionValues} value={3} />
      <StarsRatingBar descriptionValues={descriptionValues} value={4} />
      <StarsRatingBar descriptionValues={descriptionValues} value={5} />
    </StorybookComponents.Stack>
  );
};
```

#### 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/>`.

```jsx
<FormField status="error" statusMessage="This is an error message.">
  <StarsRatingBar value={0} />
</FormField>;
```

### Common use case examples

#### Collecting feedback

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

```jsx
() => {
  const [value, setValue] = React.useState(3);
  const descriptionValues = ['Very bad', 'Bad', 'Ok', 'Good', 'Very good'];

  const renderRatingBar = (
    <FormField label="How would you rate this app?">
      <StarsRatingBar
        descriptionValues={descriptionValues}
        value={value}
        onChange={setValue}
      />
    </FormField>
  );

  const renderReviewTitle = (
    <FormField label="Review Title">
      <Input placeholder="What's most important for people to know?" />
    </FormField>
  );

  const renderReview = (
    <FormField label="Review (optional)">
      <InputArea
        minHeight="90px"
        placeholder="Describe your experience. What did you like or dislike about this app?"
      />
    </FormField>
  );

  return (
    <CustomModalLayout
      primaryButtonText="Post Review"
      secondaryButtonText="Cancel"
      onCloseButtonClick={() => {}}
      title="Share Your Experience!"
    >
      <Layout gap="24px">
        <Cell span={12}>{renderRatingBar}</Cell>
        <Cell span={12}>{renderReviewTitle}</Cell>
        <Cell span={12}>{renderReview}</Cell>
      </Layout>
    </CustomModalLayout>
  );
};
```

#### Displaying feedback

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

```jsx
<Card>
  <Card.Content>
    <Box gap="18px">
      <Avatar color="A2" name={'John Doe'} />
      <Box direction="vertical" gap="6px">
        <Box>
          <Text size="small">Pauline0187 </Text>
          <Text size="small" secondary>
            / Apr 07, 2021
          </Text>
        </Box>
        <StarsRatingBar value={4} readOnly size="small" />
        <Text weight="bold">Amazing App, Amazing Support team</Text>
        <Text weight="thin">
          I love this app! I have a Membership only website with over 100 pages.
          Site Search let's a user type in any word they want to find on the
          site and it serv... <a>Read more</a>
        </Text>
      </Box>
    </Box>
  </Card.Content>
</Card>;
```

## Code

```jsx
import { StarsRatingBar } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in tests. |
| `descriptionValues` | `string[]` | — | Specifies the rate caption value labels. Array must contain all 5 strings to display the rating labels. |
| `labelValues` | `string[]` | — | Specifies the rate input value labels. |
| `name` | `string` | — | 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 |
| `readOnly` | `boolean` | — | Specifies whether the rating bar is in read-only mode. |
| `ref` | `null \| 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:

```jsx
// UniDriver
import { StarsRatingBarUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { StarsRatingBarTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { StarsRatingBarTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { StarsRatingBarTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `selectRating` | Selects a star rating bar value |
| `getSelectedRating` | Gets the selected rating (a number between 0 to 5) |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `click` | Clicks on the component root element. |
| `base` | Returns 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](invalid-url)) — 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](invalid-url)) — 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](invalid-url))
- **1.183.0** (2025-04-24) — maintenance release, no component-specific changes
- **1.167.0** (2025-03-05) — feat: add interactive mode medium ([#14580](invalid-url))
- **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