Rating

The form-grade rating control. One component covers two jobs:

• Interactive — <Rating defaultValue={0} onChange={…}> lets users pick a value.
• Read-only display — <Rating value={3.71} readOnly precision="exact"> paints an average.

Both modes share the same role="slider", the same icon stack, the same label/description/helper wiring, and the same hidden-input form integration. There's nothing to learn twice.

Why this exists

Star ratings are a universal form pattern — product reviews, support surveys, NPS, content rating — but they're full of subtle mistakes when hand-rolled:

• ❌ Stars are buttons, so users hear "button, button, button, button, button" through a screen reader.
• ❌ No keyboard support, or arrow keys jump the wrong direction in RTL.
• ❌ Half-stars get geometry wrong on touch / on retina / in RTL.
• ❌ Hover preview commits on mobile because there's no real hover.
• ❌ Form libraries see no value because there's no underlying <input>.

<Rating> fixes every one of those. The root carries role="slider" (single focus stop), each star is aria-hidden, the W3C Slider keyboard pattern is applied with RTL-aware arrow flipping, half-steps use clip-path on a layered fill (pixel-perfect), pointer math is gated to mouse (touch never gets a sticky preview), and a hidden <input name=value> ships the value to every form library.

Anatomy

┌──────────────────────────────────────────────────────┐
│  Rate your experience *               ← label        │
│  Tap a star to submit                 ← description  │
│  ★ ★ ★ ★ ☆   3 of 5                   ← track + value│
│  Please rate before submitting        ← error/helper │
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│  Rate your experience *               ← label        │
│  Tap a star to submit                 ← description  │
│  ★ ★ ★ ★ ☆   3 of 5                   ← track + value│
│  Please rate before submitting        ← error/helper │
└──────────────────────────────────────────────────────┘

• track — the role="slider" row. Tab-stops here.
• star (×N) — aria-hidden, layered <empty> + <filled> SVG. The filled layer is clipped from the trailing edge so any fraction (whole / half / 0.71) renders pixel-perfect.
• label / description / helper / error — wired via the shared useFormFieldA11y hook.

Examples

Props

Keyboard

Follows the W3C Slider pattern:

A11y

• Root is role="slider" with aria-valuemin={0}, aria-valuemax={max}, aria-valuenow={value}, aria-valuetext populated via formatValueText. Each star is aria-hidden.
• readOnly sets aria-readonly="true" + tabIndex={0} (focusable for AT, not interactive).
• disabled sets aria-disabled="true" + tabIndex={-1}.
• required sets aria-required="true"; error sets aria-invalid="true".
• Label / description / helper / error are wired via useFormFieldA11y (shared hook used by <Input>, <Textarea>, <Select>).
• Error text carries role="alert" so AT announces validation failures as they land.
• Hover preview never updates aria-valuenow — only committed values are announced.
• axe-core: 0 violations across all modes (verified in Rating.a11y.test.tsx).

RTL

• Stars visually flip — "star 1" is on the right under dir="rtl".
• Arrow keys flip — ArrowRight decreases in RTL, matching W3C Slider.
• Pointer math mirrors — clicking the right edge in RTL still picks "star 1".
• The filled clip grows from the leading edge in both directions.

Theming

<Rating> is in the theme registry as Rating. Override slots via theme.components.Rating:

const theme = createTheme({
  components: {
    Rating: {
      defaultProps: { color: 'primary', size: 'lg' },
      styleOverrides: {
        track: 'gap-2',
        starFilled: 'drop-shadow-sm',
        label: 'uppercase tracking-wide',
      },
    },
  },
});

const theme = createTheme({
  components: {
    Rating: {
      defaultProps: { color: 'primary', size: 'lg' },
      styleOverrides: {
        track: 'gap-2',
        starFilled: 'drop-shadow-sm',
        label: 'uppercase tracking-wide',
      },
    },
  },
});

Slot names: wrapper, label, description, track, star, starEmpty, starFilled, valueText, helperText.

See also

• <Slider> — for arbitrary numeric ranges where stars aren't the right metaphor.
• <RadioGroup> — for distinct, named choices (Yes / No / Maybe) rather than ordinal scales.