PixelStarRating

Pixel-art star rating display with optional interactive selection and surface-aware styling.

Renders the @pxlkit/gamification Star at 16/20/24px with crisp nearest-neighbour scaling
Gold or green tone tokens for readonly and interactive states, surface-aware (pixel / linear)
Optional showCount label renders "N/M" beside the stars
Interactive mode exposes per-star buttons; bind the rating with value + onChange (React), v-model (Vue), [(value)] or forms (Angular)
Polymorphic starIcon prop swaps in any sibling-pack glyph without forking

Status: stable
Category: cards
Since: v2.0.0

API

import { PixelStarRating } from '@pxlkit/ui-kit';

Prop	Type	Default	Description
`value`	`number`	—	Controlled rating value (0..max).
`defaultValue`	`number`	—	Uncontrolled initial rating value (0..max).
`max`	`number`	`5`	Total number of stars rendered. Default 5.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Visual size of each star — maps to 16 / 20 / 24 px for sm / md / lg.
`tone`	`'gold' \| 'green'`	`'gold'`	Color tone applied to filled stars.
`showCount`	`boolean`	`false`	When true, renders "N/M" beside the stars.
`interactive`	`boolean`	`false`	When true, exposes each star as a button that updates the rating on click.
`onChange`	`(next: number) => void`	—	Called with the new rating when the user clicks a star (interactive only).
`surface`	`'pixel' \| 'linear'`	—	Override the ambient surface (pixel \| linear).
`starIcon`	`ReactNode \| ((args: { filled: boolean; size: number; tone: StarTone }) => ReactNode)`	—	Polymorphic escape hatch. Replace the default gamification Star glyph with any custom node, or a render function called per-star with `{ filled, size, tone }` so the caller can choose a different sibling pack icon (Heart, Coin, Crown…) without forking the component. - `undefined` (default) → render the gamification `Star` for filled positions and the inline outlined rect-SVG for empty ones. - `ReactNode` → render for filled positions only; empty positions continue to use the outlined fallback for the empty-state silhouette. - `(args) => ReactNode` → render for both filled and empty positions, giving full control over the glyph in every state.

Also takes the native attributes and event handlers of <div> (HTMLAttributes<HTMLDivElement>).

ref points to <div>.

WCAG target: 2.1 AA

role=img with aria-label="N out of M" for readonly display
role=group with per-star buttons (aria-pressed) for interactive mode

Interactive mode exposes each star as a button with aria-pressed reflecting filled state; readonly mode collapses to a single aria-labeled image.

Keyboard

Key	Action	When
`Tab`	Moves focus through interactive star buttons	interactive=true
`Enter / Space`	Activates the focused star button to set the rating	interactive=true

Usage

import { PixelStarRating } from '@pxlkit/ui-kit';

export function Default() {
  return <PixelStarRating value={4} />;
}

Examples

Default

import { PixelStarRating } from '@pxlkit/ui-kit';

export function Default() {
  return <PixelStarRating value={4} />;
}

With Count

import { PixelStarRating } from '@pxlkit/ui-kit';

export function WithCount() {
  return <PixelStarRating value={3} max={5} showCount />;
}

Green Tone (Large)

import { PixelStarRating } from '@pxlkit/ui-kit';

export function GreenTone() {
  return <PixelStarRating value={5} tone="green" size="lg" />;
}

Interactive

import React from 'react';
import { PixelStarRating } from '@pxlkit/ui-kit';

export function Interactive() {
  const [rating, setRating] = React.useState(3);
  return <PixelStarRating value={rating} interactive onChange={setRating} />;
}

Custom Icon (Heart)

import { PxlKitIcon } from '@pxlkit/core';
import { Heart } from '@pxlkit/gamification';
import { PixelStarRating } from '@pxlkit/ui-kit';

export function CustomIcon() {
  return (
    <PixelStarRating
      value={3}
      starIcon={
        <PxlKitIcon icon={Heart} size={20} appearance="solid" color="#EF4444" />
      }
    />
  );
}