Add this component

npx zentauri-ui add rating

Accessibility notes

Keyboard accessible by default with semantic markup, visible focus treatment, and tokenized states. Add descriptive labels for icon-only or decorative usage.

Dependency notes

No extra runtime dependency beyond React and the package peers already covered in Installation.

Forms

Rating for product feedback

Rating renders an interactive review control for product scores, customer sentiment, support quality, marketplace cards, and survey feedback. It supports controlled and uncontrolled values, half-step selection, clear-on-repeat behavior, read-only aggregate displays, hidden form values, and icon presets powered by react-icons.

Customer sentiment

Half steps are enabled for nuanced product feedback.

Delight score

Support quality

Examples

Rating covers review forms, NPS-style feedback, marketplace cards, and read-only aggregate scores with one accessible radiogroup API.

Review score

Current value: 3.5

Delight score

Average support rating

Rating variants playground

Pick an appearance, size, icon, and behavior to preview the rating live. Toggle Show output / Show code and the snippet updates to match the selected variant.

Appearance

Size

Icon

Allow half

Allow clear

Product rating

All appearances

Every shipped appearance token at a glance. Click any swatch to load it into the playground above.

Icon: CUSTOM REACT ICON

Energy score

State: VALIDATION

Service rating

Choose a score before submitting feedback.

Rating API

Generated from the package prop types and variant definitions.

Rating

RatingProps

Variants

Prop	Type	Default
appearance	`amberaquabluecrimsoncyandefaultdestructiveelectricemeraldforestghostglass`+36	amber

State

Prop	Type	Default
defaultValue	`number \| undefined`	none
onValueChange	`((value: number) => void) \| undefined`	none
value	`number \| undefined`	none

Behavior

Prop	Type	Default
allowClear	`boolean \| undefined`	none
allowHalf	`boolean \| undefined`	none
disabled	`boolean \| undefined`	none
errorMessage	`ReactNode`	none
getLabel	`((value: number, max: number) => string) \| undefined`	none
hint	`ReactNode`	none
icon	`RatingPresetIcon \| IconType \| undefined`	none
iconClassName	`string \| undefined`	none
label	`ReactNode`	none
max	`number \| undefined`	none
name	`string \| undefined`	none
readOnly	`boolean \| undefined`	none
size	`'md' \| 'sm' \| 'lg' \| null \| undefined`	none

Inherited HTML props

Prop	Type	Default
className	`string \| undefined`	none
id	`string \| undefined`	none
onClick	`MouseEventHandler<HTMLDivElement> \| undefined`	none
style	`CSSProperties \| undefined`	none
title	`string \| undefined`	none

RatingIconVariant

RatingIconVariantProps

Behavior

Prop	Type	Default
appearance	'default' \| 'outline' \| 'ghost' \| 'blue' \| 'cyan' \| 'green' \| 'lime' \| 'mint' \| 'ocean' \| 'sapphire' \| 'lavender' \| 'ruby' \| 'red' \| 'slate' \| 'zinc' \| 'stone' \| 'royal' \| 'electric' \| 'forest' \| 'sunset' \| 'magenta' \| 'crimson' \| 'aqua' \| 'plum' \| 'sky' \| 'rose' \| 'purple' \| 'pink' \| 'orange' \| 'yellow' \| 'teal' \| 'indigo' \| 'emerald' \| 'gradient-blue' \| 'gradient-green' \| 'gradient-red' \| 'gradient-yellow' \| 'gradient-purple' \| 'gradient-teal' \| 'gradient-indigo' \| 'gradient-pink' \| 'gradient-orange' \| 'gray' \| 'violet' \| 'glass' \| 'secondary' \| 'destructive' \| 'amber' \| null \| undefined	none

RatingItemVariant

RatingItemVariantProps

Behavior

Prop	Type	Default
size	`'md' \| 'sm' \| 'lg' \| null \| undefined`	none

CSS variable overrides

Rating CSS variables

Override these rating variables on :root, a theme selector, or a component wrapper. Structural variables drive the label, hint, empty icon, focus ring, and error text; each appearance sets the active (filled) icon color.

108 variables

Pattern: --zui-<component>-<slot?>-<variant?>-<property>-<state?>-dark?

:root {
  --zui-rating-label-fg: oklch(20.8% 0.042 265.755);
  --zui-rating-hint-fg: oklch(55.4% 0.046 257.417);
  --zui-rating-gap: 0.25rem;
  --zui-rating-empty: oklch(86.9% 0.022 252.894);
  --zui-rating-ring-focus: oklch(54.6% 0.245 262.881 / 0.32);
  --zui-rating-ring-offset-focus: #ffffff;
  --zui-rating-error-fg: oklch(58.6% 0.253 17.585);
  --zui-rating-default-active: oklch(20.8% 0.042 265.755);
  --zui-rating-secondary-active: oklch(44.6% 0.043 257.281);
  --zui-rating-destructive-active: oklch(58.6% 0.253 17.585);
  --zui-rating-outline-active: oklch(44.6% 0.043 257.281);
  --zui-rating-ghost-active: oklch(37.2% 0.044 257.287);
  --zui-rating-glass-active: oklch(54.6% 0.245 262.881);
  --zui-rating-emerald-active: oklch(59.6% 0.145 163.225);
  --zui-rating-indigo-active: oklch(51.1% 0.262 276.966);
  --zui-rating-purple-active: oklch(55.8% 0.288 302.321);
  --zui-rating-pink-active: oklch(59.2% 0.249 0.584);
  --zui-rating-rose-active: oklch(58.6% 0.253 17.585);
  --zui-rating-sky-active: oklch(62.3% 0.214 259.815);
  --zui-rating-teal-active: oklch(60% 0.118 184.704);
  --zui-rating-yellow-active: oklch(79.5% 0.184 86.047);
  --zui-rating-orange-active: oklch(64.6% 0.222 41.116);
  --zui-rating-gray-active: oklch(55.1% 0.027 264.364);
  --zui-rating-amber-active: oklch(76.9% 0.188 70.08);
  --zui-rating-violet-active: oklch(54.1% 0.281 293.009);
  --zui-rating-gradient-blue-active: oklch(54.6% 0.245 262.881);
  --zui-rating-gradient-green-active: oklch(62.7% 0.194 149.214);
  --zui-rating-gradient-red-active: oklch(57.7% 0.245 27.325);
  --zui-rating-gradient-yellow-active: oklch(79.5% 0.184 86.047);
  --zui-rating-gradient-purple-active: oklch(62.7% 0.265 303.9);
  --zui-rating-gradient-teal-active: oklch(60% 0.118 184.704);
  --zui-rating-gradient-indigo-active: oklch(51.1% 0.262 276.966);
  --zui-rating-gradient-pink-active: oklch(59.2% 0.249 0.584);
  --zui-rating-gradient-orange-active: oklch(64.6% 0.222 41.116);
  --zui-rating-blue-fg: #2563eb;
  --zui-rating-cyan-fg: #0891b2;
  --zui-rating-green-fg: #16a34a;
  --zui-rating-lime-fg: #65a30d;
  --zui-rating-mint-fg: #10b981;
  --zui-rating-ocean-fg: #0284c7;
  --zui-rating-sapphire-fg: #1d4ed8;
  --zui-rating-lavender-fg: #8b5cf6;
  --zui-rating-ruby-fg: #be123c;
  --zui-rating-red-fg: #dc2626;
  --zui-rating-slate-fg: #475569;
  --zui-rating-zinc-fg: #52525b;
  --zui-rating-stone-fg: #57534e;
  --zui-rating-royal-fg: #4338ca;
  --zui-rating-electric-fg: #0ea5e9;
  --zui-rating-forest-fg: #166534;
  --zui-rating-sunset-fg: #ea580c;
  --zui-rating-magenta-fg: #c026d3;
  --zui-rating-crimson-fg: #b91c1c;
  --zui-rating-aqua-fg: #0f766e;
  --zui-rating-plum-fg: #7e22ce;
}

/* Dark theme variables follow the same names with -dark appended. */
.dark {
  --zui-rating-label-fg-dark: oklch(98.4% 0.003 247.858);
  --zui-rating-hint-fg-dark: oklch(70.4% 0.04 256.788);
}

What it does

Provide a polished rating primitive with animated fill clipping, hover previews, keyboard stepping, and the same appearance system used across Zentauri UI components.

The component keeps the visual icon row separate from the radio options so half-step values stay accessible while the display remains compact.

Composition and API

Import Rating from the rating entrypoint. Use value and onValueChange for controlled state, or defaultValue for uncontrolled state. Tune the control with max, allowHalf, allowClear, readOnly, disabled, name, size, appearance, icon, getLabel, hint, and errorMessage.

Common use cases

Use Rating anywhere a product surface needs compact sentiment input or a read-only quality signal. It fits product reviews, post-support satisfaction prompts, survey questions, testimonial cards, marketplace summaries, and admin dashboards that compare customer feedback across teams or releases.

Accessibility

Rating renders a role=radiogroup wrapper with individual role=radio options. Provide label text, use hint for helper copy, and customize getLabel when your scoring language needs more context than the default numeric value.

Next.js integration notes

Use Rating in client components when the selected value changes in the browser. Read-only aggregate displays can be rendered from server data, while interactive feedback forms should submit the hidden input or controlled value to your own server action or API route.

FAQ

Can Rating collect half-star values?

Yes. Pass allowHalf to expose half-step radio options and keep the fill clipped to the selected fractional value.

Can I use icons other than stars?

Yes. Use the built-in star, heart, flame, and thumb presets, or pass any react-icons component through the icon prop.

Does Rating work in forms?

Yes. Pass name to render a hidden input with the current numeric rating value.