KQ-1339 · RATINGS/SUMMARY
A product's ratings where the distribution is the filter: the average rolls up on snap, the stars fill from the left on glide and the five bars grow on a cascade, and pressing a bar filters the reviews below, which reflow rather than reload — leavers fade on the exit ease, the rest travel to their new places on glide and newcomers arrive from 8px inside a height that glides with them. One star at a time slides a wash between bars on snap, several toggle with checks; helpful votes roll their count and pop the thumb, and photos from reviews open in a viewer over the component's own frame, growing out of their thumbnail on glide and swiped 1:1 with a projected release. Bars are toggle buttons with roving arrows, the viewer a dialog that keeps Tab inside and gives focus back to its thumbnail.
Waylight Ridge Trail Runner
4.5 average · 1,284 ratings · all reviews · sorted by most helpful
One command — the source lands in your repo. Or copy it from the Code tab.
$ pnpm dlx shadcn@latest add @kinetiq/ratings-summary
| Prop | Type | Default | Description |
|---|---|---|---|
| bars | "rows" | "columns" | "rows" | How the distribution is drawn: horizontal bars with star and count, or a five-column histogram rising from a baseline. |
| filter | "single" | "multi" | "single" | One star at a time, with a cobalt wash that slides between bars (pressing the chosen bar again clears it), or several stars toggled together, each with a check. |
| photos | "strip" | "grid" | "off" | "strip" | Photos from reviews as one scrolling strip of thumbnails, a mosaic with a +N tile (its own column from 68rem), or left out along with the thumbnails on each review. |
| reviews | Review[] | defaultReviews | The page of reviews: author, rating, title, body, date (ms), verified, helpful count, variant and photos (alt, tint, scene). |
| distribution | number[] | defaultRatingDistribution | Ratings per star for the whole product, 1★ first. Counted from reviews when you pass your own reviews without it. |
| productName | string | "Ridge Trail Runner" | The product, shown under the heading. |
| stars / defaultStars | number[] | [] | The star filter: the ratings shown, empty for all. Controlled or uncontrolled. |
| onStarsChange | (stars: number[]) => void | — | Fires from the bar, key or Clear that changed the filter. |
| sort / defaultSort | "helpful" | "newest" | "highest" | "lowest" | "helpful" | The list's order. Controlled or uncontrolled; a change reorders the list with a layout glide. |
| onSortChange | (sort: RatingsSort) => void | — | Fires when the visitor picks an order. |
| voted / defaultVoted | string[] | [] | The reviews this visitor marked helpful. Controlled or uncontrolled. |
| onVotedChange | (voted: string[]) => void | — | Fires with every helpful mark after a vote. |
| onVote | (id: string, voted: boolean) => void | — | A review was marked helpful or unmarked. |
| pageSize | number | 5 | Reviews shown before Show more; each press adds this many, cascading in. |
| onPhotoOpen | (photoId: string, reviewId: string) => void | — | A photo was opened in the viewer. |
| now | number | Date | defaultRatingsNow | The moment relative dates count from, never the wall clock. |
| formatDate | (ms: number, now: number) => string | "3 days ago", then "Sep 12" | Review dates to text. |
| title | string | "Ratings & reviews" | The heading, and the region's name unless label is given. |
| status | "ready" | "loading" | "error" | "ready" | Whether the reviews have arrived: loading shows skeletons, error a message with Try again. |
| onRetry | () => void | — | Try again was pressed after the reviews failed to load. |
| label | string | — | The region's accessible name, when the visible title is not enough. |
| sound | boolean | false | Ticks pitched by star for bars, and for photos in the viewer; a pop for a helpful vote. |
| disabled | boolean | false | Read only: the reviews still read, nothing can be filtered, voted or opened. |
| className | string | — | Classes for the root. It is at most 560px tall and scrolls inside itself. |