# Rating

An interactive star rating input.

- Category: Core Elements
- Page: https://wunderui.com/components/rating
- Tier: Free

## Install

```bash
npx wunderui-cli add rating
```

## Import

```tsx
import { Rating, RatingCell, RatingLabel, RatingSize, RatingType, Stars } from "@/components/wunderui/rating"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { Rating } from "@/components/ui/rating"

export function RateArticle() {
  const [value, setValue] = useState(0)

  return <Rating value={value} onValueChange={setValue} aria-label="Rate this article" />
}
```

Expected result: You should see five empty stars. Click the fourth, or focus the row and press ArrowRight four times, and four stars fill with the yellow brand tone.

## Usage

```tsx
import { useState } from "react"
import { Rating } from "@/components/ui/rating"

export function Example() {
  const [value, setValue] = useState(4)

  return (
    <Rating
      value={value}
      onValueChange={setValue}
      aria-label="Rate this article"
    />
  )
}

```

## When to use

### Use Rating for

- Asking for an opinion about an article, a template or a purchase, with stars or hearts
- A survey answer from 0 to 10, such as how likely someone is to recommend you
- Showing an average score beside a product or a review, as a read-only row

### Use something else

- [Slider](https://wunderui.com/components/slider) for picking a value on a continuous range, such as a price or a volume
- [Emoji Reaction Button](https://wunderui.com/components/emoji-reaction-button) for a quick reaction to a piece of content, with a count
- [Progress](https://wunderui.com/components/progress) for a share or a completion rather than an opinion

## Keyboard

An interactive Rating is a radio group of native buttons: one Tab stop, and Arrow keys do the moving. A read-only Rating takes no focus.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the group, to the chosen option or to the first one, and out of it. The other options are skipped. |
| `ArrowRight` or `ArrowUp` | Moves to the next option and chooses it. The arrows stop at the last option and do not wrap. In right-to-left layouts ArrowLeft goes forward. |
| `ArrowLeft` or `ArrowDown` | Moves to the previous option and chooses it. The arrows stop at the first option. |
| `Home` or `End` | Chooses the first or the last option. |
| `Enter` or `Space` | Chooses the focused option. On the faces, pressing it again on the chosen face clears the answer. |

## Behavior

What the rating does with its value, hover, labels and motion.

- **Controlled:** Rating keeps no state. The value comes from you, and every choice calls the change handler with the new number, so nothing changes until you set the value.
- **Values:** Stars, hearts and faces start at 1 and use 0 for nothing chosen. The scale starts at 0, which is an answer, so pass a value outside its range while nothing is chosen yet.
- **Fractions:** A fractional value fills the nearest whole icon (3.2 fills three, 4.5 fills five), and the label keeps the number rounded to one decimal. A read-only row names the exact value.
- **Hover:** Hovering a star or a heart previews the fill up to it and returns to the value when the pointer leaves. Faces and numbers only change their background.
- **Faces:** Five faces, one answer. Choosing the chosen face again clears the value to 0.
- **Scale:** Eleven options from 0 to 10 in a 480 px row that never grows past its container. Below 352 px they wrap into two rows, so use a left or right label instead of the tooltip on a narrow screen.
- **Labels:** Left and right put the number beside the row. The tooltip shows it in a dark bubble with an arrow above the chosen option, and the bubble is hidden from assistive technology.
- **Read-only:** Read-only renders one image, named Rated 3.5 out of 5 or by your aria-label. The options are plain spans without hover, focus or a Tab stop.
- **Direction:** In right-to-left layouts ArrowLeft goes forward and ArrowRight goes back. The order of the icons follows the document direction.
- **Motion:** Stars and hearts change their fill at once. Faces and numbers fade their background quickly, and nothing moves or scales.
- **Reduced motion:** There is no movement to remove, so reduced motion changes nothing. The background changes are short fades and stay.

## Anatomy

- `Rating`: The group of options. Interactive it is a radio group with one Tab stop, and read-only it is a single image that reads Rated 3.5 out of 5, named by an aria-label.
- `Option`: One radio of the group: a star or heart (24 px), a face (48 px) or a scale number (40 px high). Hover previews the fill of stars and hearts, and a click or arrow key chooses.
- `Filled icon`: A star in the yellow brand tone or a heart in the pink one, filled up to the value.
- `Empty icon`: The outline in the control border colour for the options beyond the value.
- `Value label`: The number beside the row, on the left or right. The tooltip option shows it in a dark bubble with an arrow above the chosen option instead.
- `RatingCell`: A read-only star row with the value on the right, made for table cells.
- `Stars`
- `Bubble`

## Best practices

### Do

- Pick the type for the question: stars for an opinion, hearts for favorites, emojis for a mood, and scale for a 0 to 10 survey answer such as Net Promoter Score.
- Give every interactive Rating a visible question and tie it with aria-labelledby, or set an aria-label. The default name is only Rating.
- Set read-only when you display an average. A fractional value such as 3.5 fills the nearest icon and keeps the exact number in the accessible name.
- Show the label on the right when the number matters. Without it, a score of 4.5 is only a row of icons.
- Show a comment field after a low score, so people can say what went wrong. Send the score only when they confirm it.

### Don't

- Don't use the tooltip label against the top edge of a container. The bubble floats about 32 px above the row and takes no space in the layout, so leave room for it.
- Don't expect hover to choose. It only previews the fill of stars and hearts; a click or arrow key chooses, and arrows move and choose in one step.
- Don't use the emojis type for a required answer. Clicking the chosen face again clears it and sends 0.

## API reference

### Rating

| Prop | Type | Default | Description |
|---|---|---|---|
| value* | number |  | The current value, a controlled number. Stars, hearts and faces count from 1 and use 0 for nothing; the scale counts from 0. A fraction fills the nearest icon. |
| aria-label | string |  | Names the group ("Rating" by default); read-only, it replaces "Rated 3.5 out of 5". |
| aria-labelledby | string |  | Id of a visible label that names the group, instead of `aria-label`. |
| className | string |  | Extra classes for the root, for example `justify-center` or a width for the scale. |
| label | "none" \| "tooltip" \| "left" \| "right" | "none" | Where the value is shown: `none` (default), `left` or `right` of the row, or `tooltip` in a bubble above the chosen option. |
| max | number |  | The number of stars or hearts, 5 by default. For the scale it is the number of options, 11 by default, so the highest answer is `max - 1`. It has no effect on the faces. |
| onValueChange | (value: number) => void |  | Called with the number the person chose, by click or arrow key. Choosing the chosen face again sends 0. Without it the rating cannot change. |
| readOnly | boolean | false | Shows the score as one image without focus or hover. Use it for an average. |
| size | "sm" \| "md" | "md" | `md` (default) is the 24 px target of an input. `sm` is the compact display of a read-only star or heart row: 12 px icons with a filled grey for the empty ones, for a product card or a review line. It is ignored while the rating is interactive and for faces and the scale. It replaces Stars. |
| type | "scale" \| "stars" \| "hearts" \| "emojis" | "stars" | What the options look like: `stars` (default), `hearts`, `emojis` for five faces or `scale` for a 0 to 10 row. |

### RatingCell

| Prop | Type | Default | Description |
|---|---|---|---|
| value* | number |  | The score to show, as a number up to `max`. A fraction fills the nearest star and the number is written on the right. |
| max | number | 5 | The number of stars in the row, 5 by default. |

### Stars

| Prop | Type | Default |
|---|---|---|
| value* | number |  |
| className | string |  |
| max | number | 5 |

## Examples

### Value: from empty to full, as a read-only row

```tsx
import { Rating } from "@/components/ui/rating"

export function Example() {
  return (
    <Rating value={0} readOnly label="right" />
  )
}

```

### Max: three, five or ten stars

```tsx
import { useState } from "react"
import { Rating } from "@/components/ui/rating"

export function Example() {
  const [value, setValue] = useState(2)

  return (
    <Rating
      max={3}
      value={value}
      onValueChange={setValue}
      aria-label="Rate this article"
    />
  )
}

```

### Mode: interactive or read-only

```tsx
import { useState } from "react"
import { Rating } from "@/components/ui/rating"

export function Example() {
  const [value, setValue] = useState(4)

  return (
    <Rating
      value={value}
      onValueChange={setValue}
      aria-label="Rate this article"
    />
  )
}

```

### Compact: a read-only row of small stars or hearts

```tsx
import { Rating } from "@wunderui/react"

export function ProductRating() {
  return (
    <div className="flex items-center gap-2 text-xs text-text-secondary">
      <Rating readOnly size="sm" value={4} aria-label="4 out of 5 stars" />
      <span>4.0 (128)</span>
    </div>
  )
}
```

## In context

### Reviews summary: the average and how the stars are spread

A read-only rating beside the average and the number of reviews. The bars below show the share of each star level.

```tsx
import { Rating } from "@/components/ui/rating"
import { Progress } from "@/components/ui/progress"

export function ReviewsSummary() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <div className="flex items-center gap-4">
        <span className="text-3xl font-semibold tabular-nums text-foreground">4.8</span>
        <div className="flex flex-col gap-1">
          <Rating value={4.8} readOnly aria-label="Rated 4.8 out of 5" />
          <span className="text-xs text-text-tertiary">From 1,248 reviews</span>
        </div>
      </div>
      <ul className="flex flex-col gap-2">
        <li className="flex items-center gap-3 text-sm text-text-secondary">
          <span className="w-12 shrink-0">5 stars</span>
          <Progress value={78} className="flex-1" aria-label="5 stars" />
          <span className="w-10 shrink-0 text-right tabular-nums">78%</span>
        </li>
        <li className="flex items-center gap-3 text-sm text-text-secondary">
          <span className="w-12 shrink-0">4 stars</span>
          <Progress value={14} className="flex-1" aria-label="4 stars" />
          <span className="w-10 shrink-0 text-right tabular-nums">14%</span>
        </li>
        <li className="flex items-center gap-3 text-sm text-text-secondary">
          <span className="w-12 shrink-0">3 stars</span>
          <Progress value={5} className="flex-1" aria-label="3 stars" />
          <span className="w-10 shrink-0 text-right tabular-nums">5%</span>
        </li>
        <li className="flex items-center gap-3 text-sm text-text-secondary">
          <span className="w-12 shrink-0">2 stars</span>
          <Progress value={2} className="flex-1" aria-label="2 stars" />
          <span className="w-10 shrink-0 text-right tabular-nums">2%</span>
        </li>
        <li className="flex items-center gap-3 text-sm text-text-secondary">
          <span className="w-12 shrink-0">1 star</span>
          <Progress value={1} className="flex-1" aria-label="1 star" />
          <span className="w-10 shrink-0 text-right tabular-nums">1%</span>
        </li>
      </ul>
    </div>
  )
}

```

### Recommend survey: a 0 to 10 score with a reason

Nothing is chosen at first and Send score stays disabled. The question names the group, so a screen reader reads it with the options.

```tsx
import { useState } from "react"
import { Rating } from "@/components/ui/rating"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import { Label } from "@/components/ui/label"
import { Textarea } from "@/components/ui/textarea"

export function RecommendSurvey() {
  // -1 means nothing is chosen yet; on the scale 0 is an answer.
  const [score, setScore] = useState<number | null>(null)
  const [sent, setSent] = useState(false)

  return (
    <Card className="w-full max-w-xl">
      <CardHeader>
        <CardTitle id="nps-question">How likely are you to recommend WunderUI to a colleague?</CardTitle>
      </CardHeader>
      <CardContent className="flex flex-col gap-4">
        <Rating type="scale" value={score ?? -1} onValueChange={setScore} aria-labelledby="nps-question" />
        <div className="flex justify-between text-xs text-text-tertiary">
          <span>Not likely</span>
          <span>Very likely</span>
        </div>
        <div className="flex flex-col gap-2">
          <Label htmlFor="reason">What is the main reason for your score?</Label>
          <Textarea id="reason" placeholder="The tokens make handoff painless…" />
        </div>
        {sent ? (
          <p role="status" className="text-sm text-text-secondary">
            Thanks, your score of {score} is saved.
          </p>
        ) : (
          <Button className="self-end" disabled={score === null} onClick={() => setSent(true)}>
            Send score
          </Button>
        )}
      </CardContent>
    </Card>
  )
}

```

### Support feedback: stars, then a comment for a low score

The label on the right shows the number. A score of three or less asks what went wrong; a higher one goes straight to Submit.

```tsx
import { useState } from "react"
import { Rating } from "@/components/ui/rating"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
import { Label } from "@/components/ui/label"
import { Textarea } from "@/components/ui/textarea"

export function SupportFeedback() {
  const [stars, setStars] = useState(0)
  const [sent, setSent] = useState(false)

  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <CardTitle id="support-question">How was your support experience?</CardTitle>
        <CardDescription>Ticket #48219 was resolved today.</CardDescription>
      </CardHeader>
      <CardContent className="flex flex-col gap-4">
        <Rating value={stars} onValueChange={setStars} label="right" aria-labelledby="support-question" />
        {stars > 0 && stars <= 3 && (
          <div className="flex flex-col gap-2">
            <Label htmlFor="comment">What could we have done better?</Label>
            <Textarea id="comment" />
          </div>
        )}
        {sent ? (
          <p role="status" className="text-sm text-text-secondary">
            Thanks for your feedback.
          </p>
        ) : (
          <Button className="self-end" disabled={stars === 0} onClick={() => setSent(true)}>
            Submit rating
          </Button>
        )}
      </CardContent>
    </Card>
  )
}

```

### Mood check: five faces, one answer

Choosing a face answers at once. Choosing the same face again clears the answer and sends 0.

```tsx
import { useState } from "react"
import { Rating } from "@/components/ui/rating"
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"

export function MoodCheck() {
  const [mood, setMood] = useState(0)

  return (
    <Card className="w-full max-w-sm">
      <CardHeader>
        <CardTitle>Quick feedback</CardTitle>
        <CardDescription>How is your experience so far?</CardDescription>
      </CardHeader>
      <CardContent className="flex flex-col items-center gap-4">
        <Rating type="emojis" value={mood} onValueChange={setMood} aria-label="How is your experience so far?" />
        <p role="status" className="text-sm text-text-secondary">
          {mood === 0 ? "Choose a face." : "Thanks, we saved your answer."}
        </p>
      </CardContent>
    </Card>
  )
}

```

## For AI agents

`get_component("rating")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
