Rating
FreeCollect or show a score as stars, hearts, five faces or a 0 to 10 scale.
npx wunderui-cli add ratingPlayground
Installation
npx wunderui-cli add ratingWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { Rating } from "@/components/wunderui/rating"
import type {
RatingLabel,
RatingSize,
RatingType,
} from "@/components/wunderui/rating"Then use it:
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.
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 for
- Slider for picking a value on a continuous range, such as a price or a volume
- Emoji Reaction Button for a quick reaction to a piece of content, with a count
- Progress for a share or a completion rather than an opinion
Value
The value is the number of filled icons, from 0 (nothing chosen) to the maximum. A fraction such as 3.5 fills the nearest icon and keeps its exact number in the label and accessible name.
Max
Stars and hearts show five icons by default, and the maximum changes how many. The scale type counts from 0 up and shows eleven options by default.
Mode
Interactive, a rating is a radio group: one Tab stop, and the arrow keys move and choose. Read-only, it is one image that only shows the score.
Compact
size="sm" turns a read-only star or heart row into the small display of a product card or a review line: 12 px icons with a filled grey for the empty ones. The value rounds to whole icons, and aria-label names the row. An interactive rating ignores the size and keeps its 24 px targets. It replaces Stars.
Keyboard interactions
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.
- TaborShift+Tab
- Moves focus into the group, to the chosen option or to the first one, and out of it. The other options are skipped.
- ArrowRightorArrowUp
- 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.
- ArrowLeftorArrowDown
- Moves to the previous option and chooses it. The arrows stop at the first option.
- HomeorEnd
- Chooses the first or the last option.
- EnterorSpace
- Chooses the focused option. On the faces, pressing it again on the chosen face clears the answer.
Behavior and motion
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
The figure marks the stars type with a label on the right. Faces and the 0 to 10 scale have the same group and options, with faces or numbers in place of the icons.
- 1data-slot="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.
- 2
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.
- 3Optional
A star in the yellow brand tone or a heart in the pink one, filled up to the value.
- 4Optional
The outline in the control border colour for the options beyond the value.
- 5Optional
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.
- data-slot="rating-bubble"Optional
- Optional
A read-only star row with the value on the right, made for table cells.
- Optional
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.
- Do
Give every interactive Rating a visible question and tie it with aria-labelledby, or set an aria-label. The default name is only Rating.
- Do
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.
- Do
Show the label on the right when the number matters. Without it, a score of 4.5 is only a row of icons.
- Do
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
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
Don't use the emojis type for a required answer. Clicking the chosen face again clears it and sends 0.
API reference
One table per part. None of them wraps a primitive, so these tables list every prop; Rating is controlled and you own the value.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| type | "scale" | "stars" | "hearts" | "emojis" | "stars" | What the options look like: (default), , for five faces or for a 0 to 10 row. |
| value required | 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. |
| onValueChange | (value) => 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. |
| label | "none" | "tooltip" | "left" | "right" | "none" | Where the value is shown: (default), or of the row, or 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 . It has no effect on the faces. |
| readOnly | boolean | false | Shows the score as one image without focus or hover. Use it for an average. |
| size | "sm" | "md" | "md" | (default) is the 24 px target of an input. 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. |
| 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 . |
| className | string | — | Extra classes for the root, for example or a width for the scale. |
A read-only star row with the value on the right, made for table cells.
| Prop | Type | Default | Description |
|---|---|---|---|
| value required | number | — | The score to show, as a number up to . 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. |
| Prop | Type | Default | Description |
|---|---|---|---|
| value required | number | — | |
| max | number | 5 |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("rating")npx wunderui-cli add ratingThe full library index for assistants is at /llms.txt.