Component reference
Rating
An editable product rating with local feedback.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Width adapts to the available space
"use client";
import { useState } from "react";
import { Badge, Button, Rating } from "@pimolu/react";
function InteractiveRating() {
const [value, setValue] = useState(3);
return (
<div className="grid gap-5 min-w-0">
<div className="flex flex-wrap items-center gap-3 min-w-0">
<Badge variant={value > 0 ? "primary" : "neutral"}>
{value > 0 ? `${value} of 5` : "Not rated"}
</Badge>
<Button
size="sm"
appearance="ghost"
onClick={() => setValue(0)}
disabled={value === 0}
>
Reset
</Button>
</div>
<Rating
label="Product rating"
value={value}
onValueChange={setValue}
allowClear
/>
<p className="text-sm text-muted leading-relaxed">
Click the selected star again to clear the rating. Arrow keys,
Home and End also work.
</p>
</div>
);
}
export function DemoExample() {
return (<InteractiveRating />);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Sizes
sm, md and lg scale the stars and the visible label together.
Read-only
readOnly keeps the radiogroup semantics and announces aria-readonly, but clicks and keys do not change the value.
Disabled and custom scales
max changes the number of stars; getLabel replaces the default accessible star labels; disabled removes every star from the tab order.
Usage
Keep the numeric rating separate from the number of reviews and define the scale clearly.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluRatingProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
value | number | undefined | — | Controlled rating. Use 0 for "no rating". |
defaultValue | number | undefined | 0 | Initial rating when uncontrolled. Defaults to 0. |
onValueChange | ((value: number) => void) | undefined | — | Called with the next rating, or 0 when cleared. |
max | number | undefined | 5 | Number of stars. Defaults to 5. |
readOnly | boolean | undefined | false | Show the rating without allowing changes. |
disabled | boolean | undefined | false | Public Pimolu prop; see the source declaration for details. |
size | PimoluRatingSize | undefined | "md" | Visual size. Defaults to "md". |
allowClear | boolean | undefined | false | Click the current rating again to clear it. Defaults to false. |
label | ReactNode | — | Visible label, also used to name the group. |
getLabel | ((value: number) => string) | undefined | "N star(s)" | Accessible name for each star. Defaults to "N star(s)". |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
children | ReactNode | — | Standard React/HTML attribute. |
onClick | MouseEventHandler<HTMLDivElement> | undefined | — | Standard React/HTML attribute. |
valuenumber | undefinedNo default extracted.
Controlled rating. Use 0 for "no rating".
defaultValuenumber | undefinedDefault: 0
Initial rating when uncontrolled. Defaults to 0.
onValueChange((value: number) => void) | undefinedNo default extracted.
Called with the next rating, or 0 when cleared.
maxnumber | undefinedDefault: 5
Number of stars. Defaults to 5.
readOnlyboolean | undefinedDefault: false
Show the rating without allowing changes.
disabledboolean | undefinedDefault: false
Public Pimolu prop; see the source declaration for details.
sizePimoluRatingSize | undefinedDefault: "md"
Visual size. Defaults to "md".
allowClearboolean | undefinedDefault: false
Click the current rating again to clear it. Defaults to false.
labelReactNodeNo default extracted.
Visible label, also used to name the group.
getLabel((value: number) => string) | undefinedDefault: "N star(s)"
Accessible name for each star. Defaults to "N star(s)".
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
childrenReactNodeNo default extracted.
Standard React/HTML attribute.
onClickMouseEventHandler<HTMLDivElement> | undefinedNo default extracted.
Standard React/HTML attribute.
Accessibility
- Name the rating control and check keyboard selection; do not communicate the value only with stars.