Rating

Rating lets users provide a visual rating (stars, icons, emojis, etc.) through mouse, hover preview, or keyboard interaction. It supports controlled and uncontrolled usage and is fully accessible.

---

Usage

Basic usage (uncontrolled)

import { Rating } from '@nofinite/nui';

<Rating />;

Controlled usage

const [value, setValue] = useState(3);

<Rating value={value} onChange={setValue} />;

---

Variants

Rating does not have visual variants, but supports custom icons.

<Rating />
<Rating icon="♡" iconFilled="♥" />
<Rating icon="🙂" iconFilled="😁" />

Guidelines:

• Use default stars for general feedback.
• Use emojis or custom icons for playful or emotional contexts (e.g., reactions).

---

Sizes

<Rating size="sm" />
<Rating size="md" />
<Rating size="lg" />

Available sizes:

• sm – compact (16px)
• md – default (20px)
• lg – large emphasis (28px)

---

States

<Rating />
<Rating value={4} />
<Rating value={2} max={10} />

State behavior:

• Hover – previews rating before selection.
• Selected – filled icons up to the chosen value.
• Keyboard – ArrowLeft / ArrowRight adjusts value.

---

Native Props / Composition

Rating renders a focusable container and forwards interaction internally.

<Rating className="my-rating" onChange={(v) => console.log(v)} />

Custom styling:

<Rating className="custom-rating-theme" />

---

Props

Prop	Type	Default	Description
value	number	—	Current rating (controlled mode)
max	number	5	Maximum number of rating items
onChange	(value: number) => void	—	Called when rating changes
icon	ReactNode	☆	Icon for unfilled state
iconFilled	ReactNode	★	Icon for filled state
size	"sm" | "md" | "lg"	md	Size of the rating icons
className	string	""	Additional class names

---

Behavior Notes

• Works in controlled and uncontrolled modes.

• Hover state temporarily overrides the displayed value.

• Keyboard navigation:

  • ArrowRight → increase rating
  • ArrowLeft → decrease rating

• Value is clamped between 1 and max.

<Rating value={4} onChange={setValue} />

---

Accessibility

• Renders as a radiogroup with individual radio items.
• Keyboard focusable container.
• Arrow key navigation supported.
• Uses aria-checked for current selection.

Example:

<Rating aria-label="Product rating" />

---

Layout

• Inline-flex layout.
• Takes only the width required by icons.
• Can be placed inside text, cards, or forms.

<Rating style={{ marginTop: 8 }} />

---

Best Practices

Do

• Use controlled mode when storing ratings in state or forms.
• Provide clear visual feedback using filled icons.
• Match icon style with product tone (stars vs emojis).

Don’t

• Use too many icons (max) for simple feedback.
• Rely only on hover for critical information.
• Nest interactive elements inside Rating.