# Rating
> Stars or bolts that flicker on as you hover, with half steps.
Category: Forms. Docs: https://neonkit.heyaadi.com/components/rating
## Installation
```bash
npx shadcn@latest add https://neonkit.heyaadi.com/r/rating.json
```
With the `@neonkit` namespace configured: `npx shadcn@latest add @neonkit/rating`.
npm dependencies: none. Also needs `lib/utils.ts` (`cn`) and `lib/neon.ts` (`neonVars`), which the CLI adds.
Builds on: [Icons](https://neonkit.heyaadi.com/components/icons.md). The CLI installs them too.
## Usage
```tsx
import { Rating } from "@/components/ui/rating"
```
## Examples
### Review prompt
Hover previews a value and onHoverChange lets the caption follow it. Clicking the current value clears it.
```tsx
"use client";
import * as React from "react";
import { Rating } from "@/components/ui/rating";
const verdicts = ["", "Not for me", "Could be better", "Decent", "Really good", "Perfect"];
export default function RatingDemo() {
const [value, setValue] = React.useState(4);
const [hover, setHover] = React.useState(null);
const shown = hover ?? value;
return (
How was your order?
Flat white, oat · Halden Street Roasters
(v ? `${v} of ${max}, ${verdicts[v]}` : "No rating")}
/>
{shown ? verdicts[shown] : "Tap a star to rate"}
);
}
```
### Half steps
With allowHalf, the left half of an icon picks the half value and the arrow keys move by 0.5.
```tsx
"use client";
import * as React from "react";
import { Rating } from "@/components/ui/rating";
export default function RatingHalfSteps() {
const [score, setScore] = React.useState(3.5);
return (
Past Lives
2023 · Celine Song
{score ? score.toFixed(1) : "–"}
);
}
```
### Read-only average
Read-only ratings show fractional values exactly and are announced as an image.
```tsx
import { Rating } from "@/components/ui/rating";
const distribution = [
{ stars: 5, share: 71 },
{ stars: 4, share: 19 },
{ stars: 3, share: 6 },
{ stars: 2, share: 2 },
{ stars: 1, share: 2 },
];
export default function RatingReadOnly() {
return (
);
}
```
### Icons and colors
```tsx
import { Rating } from "@/components/ui/rating";
export default function RatingIcons() {
return (
Class intensity
Would rewatch
Overall
);
}
```
### Sizes
```tsx
import { Rating } from "@/components/ui/rating";
export default function RatingSizes() {
return (
);
}
```
## API reference
### Rating
Also accepts native div attributes, and the ref points at the icon row. className and style go to the icon row.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number` | — | Controlled value, from 0 (unrated) to max. |
| `defaultValue` | `number` | `0` | Initial value when uncontrolled. |
| `onValueChange` | `(value: number) => void` | — | Called on click or key press. Clicking the current value sends 0. |
| `max` | `number` | `5` | Number of icons. |
| `allowHalf` | `boolean` | `false` | Half values from the pointer and in 0.5 keyboard steps. |
| `icon` | `"star" \| "bolt" \| "heart"` | `"star"` | The icon shape. |
| `readOnly` | `boolean` | `false` | Display only. Not focusable, announced as an image with the value. |
| `disabled` | `boolean` | `false` | Dims the icons and ignores input. |
| `label` | `ReactNode` | — | Visible label above the icons. Names the control. |
| `formatValue` | `(value: number, max: number) => string` | `"3.5 of 5"` | Text read to screen readers for the value. |
| `onHoverChange` | `(value: number \| null) => void` | — | The previewed value while the pointer is over the icons, then null. |
| `name` | `string` | — | Submits the value with a surrounding form. |
| `color` | `NeonColor` | `inherited` | Palette name or hex. Falls back to --neon-accent, then cyan. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Icon size: 16, 24 or 32px. |
| `containerClassName` | `string` | — | Classes for the outer block when a label is set. |
## Accessibility
- With name, a form reset puts back the starting rating.
- The icon row is a role="slider" with aria-valuetext such as "3.5 of 5", or "No rating" at 0.
- Right and Up raise the value, Left and Down lower it, Home clears and End sets the maximum. Number keys jump straight to a value.
- Without a visible label, pass aria-label.
- Newly lit icons flicker on in sequence. With reduced motion they switch on without the flicker.
## Source
`components/ui/rating.tsx`
```tsx
"use client";
import * as React from "react";
import { Heart, Star, Zap } from "@/components/ui/icons";
import { cn } from "@/lib/utils";
import { neonVars, type NeonColor } from "@/lib/neon";
const icons = { star: Star, bolt: Zap, heart: Heart } as const;
// The star glyph sits small in its 24px box (about 13px across). Cropping the view box to it
// brings it level with the bolt and heart; the stroke is divided by the same factor so the tube
// keeps its weight.
const frames: Record = {
star: { viewBox: "3 3 18 18", scale: 24 / 18 },
bolt: { viewBox: "0 0 24 24", scale: 1 },
heart: { viewBox: "0 0 24 24", scale: 1 },
};
// Cells touch, so the padding is the visual gap and there are no dead zones.
const sizes = {
sm: { cell: "p-0.5", icon: "size-4", stroke: 2, label: "text-xs" },
md: { cell: "p-[3px]", icon: "size-6", stroke: 1.75, label: "text-sm" },
lg: { cell: "p-1", icon: "size-8", stroke: 1.5, label: "text-sm" },
} as const;
// Each tube strikes, drops out once, then holds. Icons light one after another.
const STAGGER = 70;
const keyframes = `@keyframes neonkit-rating-ignite{0%{opacity:0}14%{opacity:.9}26%{opacity:.2}44%{opacity:1}56%{opacity:.55}72%,100%{opacity:1}}`;
function clamp(value: number, lower: number, upper: number) {
return Math.min(upper, Math.max(lower, value));
}
function defaultValueText(value: number, max: number) {
if (value <= 0) return "No rating";
const shown = Number.isInteger(value) ? String(value) : value.toFixed(1);
return `${shown} of ${max}`;
}
type Ignition = {
display: number;
/** Bumped per icon each time it goes from dark to lit, to replay the flicker. */
keys: number[];
delays: number[];
/** Last lit fraction, kept while an icon fades out so its clip doesn't jump. */
fills: number[];
count: number;
};
export interface RatingProps
extends Omit<
React.HTMLAttributes,
"color" | "defaultValue" | "onChange" | "children"
> {
/** Palette name or any hex color. Inherits `--neon-accent` when omitted. */
color?: NeonColor;
size?: keyof typeof sizes;
value?: number;
defaultValue?: number;
onValueChange?: (value: number) => void;
/** Number of icons. */
max?: number;
/** Allows half values from the pointer (left half of an icon) and the arrow keys. */
allowHalf?: boolean;
icon?: keyof typeof icons;
/** Display only: no focus or input, announced as an image with the value. */
readOnly?: boolean;
disabled?: boolean;
/** Visible label above the icons. Also names the control. */
label?: React.ReactNode;
/** Text read to screen readers. Defaults to "3.5 of 5". */
formatValue?: (value: number, max: number) => string;
/** Called with the previewed value while the pointer moves over the icons, and null when it leaves. */
onHoverChange?: (value: number | null) => void;
/** Submits the value under this name with a surrounding form. */
name?: string;
/** Classes for the outer block when a label is set. */
containerClassName?: string;
}
const Rating = React.forwardRef(
(
{
className,
containerClassName,
style,
color,
size = "md",
value: valueProp,
defaultValue = 0,
onValueChange,
max = 5,
allowHalf = false,
icon = "star",
readOnly = false,
disabled = false,
label,
formatValue = defaultValueText,
onHoverChange,
name,
id: idProp,
"aria-label": ariaLabel,
"aria-labelledby": ariaLabelledBy,
onPointerMove,
onPointerLeave,
onClick,
onKeyDown,
...props
},
ref,
) => {
const autoId = React.useId();
const id = idProp ?? autoId;
const labelId = `${id}-label`;
const valueTextId = `${id}-value`;
const controlRef = React.useRef(null);
React.useImperativeHandle(ref, () => controlRef.current as HTMLDivElement);
const [uncontrolled, setUncontrolled] = React.useState(defaultValue);
const isControlled = valueProp !== undefined;
const value = clamp(isControlled ? valueProp : uncontrolled, 0, max);
const [hover, setHover] = React.useState(null);
// After a click clears the rating, the pointer is still over that icon.
// Hold the preview off until it moves to a different value.
const clearedAt = React.useRef(null);
const interactive = !readOnly && !disabled;
const display = interactive && hover !== null ? hover : value;
const Icon = icons[icon];
const frame = frames[icon];
const s = sizes[size];
const valueText = formatValue(value, max);
const [ignition, setIgnition] = React.useState(() => ({
display,
keys: [],
delays: [],
fills: Array.from({ length: max }, (_, i) => clamp(display - i, 0, 1)),
count: 0,
}));
if (ignition.display !== display) {
const keys = [...ignition.keys];
const delays = [...ignition.delays];
const fills = [...ignition.fills];
let order = 0;
for (let i = 0; i < max; i++) {
const before = clamp(ignition.display - i, 0, 1);
const after = clamp(display - i, 0, 1);
if (after > 0) fills[i] = after;
if (before === 0 && after > 0 && display > ignition.display) {
keys[i] = ignition.count + 1;
delays[i] = order++ * STAGGER;
}
}
setIgnition({ display, keys, delays, fills, count: ignition.count + 1 });
}
// A form reset puts the starting rating back.
const hiddenRef = React.useRef(null);
const initialValue = React.useRef(value);
const resetRef = React.useRef<() => void>(() => {});
React.useEffect(() => {
resetRef.current = () => {
const initial = initialValue.current;
if (initial === value) return;
if (!isControlled) setUncontrolled(initial);
onValueChange?.(initial);
};
});
React.useEffect(() => {
const form = hiddenRef.current?.form;
if (!form) return;
const onReset = () => resetRef.current();
form.addEventListener("reset", onReset);
return () => form.removeEventListener("reset", onReset);
}, []);
function setHoverValue(next: number | null) {
if (next === hover) return;
setHover(next);
onHoverChange?.(next);
}
function commit(next: number) {
const snapped = clamp(allowHalf ? Math.round(next * 2) / 2 : Math.round(next), 0, max);
if (snapped === value) return;
if (!isControlled) setUncontrolled(snapped);
onValueChange?.(snapped);
}
function valueFromPointer(event: React.PointerEvent | React.MouseEvent) {
const cell = (event.target as HTMLElement).closest("[data-rating-index]");
if (!cell || !event.currentTarget.contains(cell)) return null;
const index = Number(cell.dataset.ratingIndex);
if (!allowHalf) return index + 1;
const rect = cell.getBoundingClientRect();
const rtl = getComputedStyle(cell).direction === "rtl";
const offset = rtl ? rect.right - event.clientX : event.clientX - rect.left;
return offset < rect.width / 2 ? index + 0.5 : index + 1;
}
function handlePointerMove(event: React.PointerEvent) {
onPointerMove?.(event);
if (!interactive || event.pointerType === "touch") return;
const next = valueFromPointer(event);
if (next === null) return;
if (clearedAt.current !== null) {
if (next === clearedAt.current) return;
clearedAt.current = null;
}
setHoverValue(next);
}
function handlePointerLeave(event: React.PointerEvent) {
onPointerLeave?.(event);
clearedAt.current = null;
setHoverValue(null);
}
function handleClick(event: React.MouseEvent) {
onClick?.(event);
if (!interactive || event.defaultPrevented) return;
const next = valueFromPointer(event);
if (next === null) return;
if (next === value) {
commit(0);
clearedAt.current = next;
setHoverValue(null);
} else {
commit(next);
}
}
function handleKeyDown(event: React.KeyboardEvent) {
onKeyDown?.(event);
if (!interactive || event.defaultPrevented) return;
const step = allowHalf ? 0.5 : 1;
const rtl = getComputedStyle(event.currentTarget).direction === "rtl";
const forward = rtl ? "ArrowLeft" : "ArrowRight";
const back = rtl ? "ArrowRight" : "ArrowLeft";
let next: number | undefined;
if (event.key === forward || event.key === "ArrowUp") next = value + step;
else if (event.key === back || event.key === "ArrowDown") next = value - step;
else if (event.key === "Home") next = 0;
else if (event.key === "End") next = max;
else if (/^[0-9]$/.test(event.key) && !event.metaKey && !event.ctrlKey && !event.altKey) {
next = Math.min(Number(event.key), max);
}
if (next === undefined) return;
event.preventDefault();
setHoverValue(null);
commit(next);
}
const accessibleName = label ? labelId : ariaLabelledBy;
const control = (