SvRating

A star rating control built on the WAI-ARIA slider pattern - with hover preview, keyboard support, optional half steps, and a read-only mode.

SvRating collects a score (a product review) or displays an aggregate (a read-only average with half stars). It is controlled: drive value from your state and update it in onChange. It uses the grid's --sg-rating-* tokens so a standalone rating matches the in-grid rating editor, and it carries the shared editor contract (label, hint, validation, dir/RTL) through SvField. Star aria-labels are localizable via messages.

Related: SvSwitchButton · SvRadioGroup · Buttons & toggles overview

Installation

Add it with the CLI - this drops a ready-to-edit SvRating starter into your app:

Prefer to see it first? npx @svgrid/ui try rating opens it in a throwaway sandbox - no project needed.

Or install the package and import it directly. SvRating ships free in @svgrid/grid and is part of the grid's editor kit - the same control SvGrid mounts when you edit a matching cell:

The examples on this page import from @svgrid/grid:

<script lang="ts">
  import { SvRating } from '@svgrid/grid'

  // The bound value behind each example below.
  let score = $state(0)
</script>

import { SvRating } from '@svgrid/grid'

Example

<script lang="ts">
  import { SvRating } from '@svgrid/grid'
  let score = $state(4)
</script>

<SvRating label="Your rating" value={score} onChange={(v) => (score = v)} />

Props

Helper type: RatingMessages = { label: string; star: string; stars: string } (defaults Rating / star / stars).

Examples

Interactive review with a live label

Read value back to show the picked score as the user hovers and clicks:

<script lang="ts">
  let score = $state(0)
</script>

<SvRating value={score} onChange={(v) => (score = v)} />
<span>{score ? `${score} / 5` : 'Not rated'}</span>

Read-only aggregate with half stars

Combine readonly and allowHalf to render an average like 4.5:

<SvRating readonly allowHalf value={4.5} label="Average rating" />

Localized labels

Override messages to translate the group name and per-star announcements:

<SvRating value={score} onChange={(v) => (score = v)}
  messages={{ label: 'Bewertung', star: 'Stern', stars: 'Sterne' }} />

Custom scale submitted with a form

max is not fixed at five - raise it for a 10-point scale, and give it a name so a plain form submit carries the numeric value in a hidden input:

<form>
  <SvRating
    name="nps"
    label="How likely are you to recommend us?"
    max={10}
    value={score}
    onChange={(v) => (score = v)}
  />
</form>

Theming tip: the stars read --sg-rating-on (filled) and --sg-rating-empty (empty), the same tokens as the in-grid rating editor, so a standalone rating stays visually in sync with one shown in a cell.

Accessibility

• The control follows the ARIA slider pattern, named by a visible label, ariaLabel, or the messages.label fallback.
• Keyboard adjusts the value; each star exposes a label like 3 stars built from messages.star / messages.stars.
• readonly and disabled remove the pointer affordance; disabled also dims the stars. Half fills render via a per-star gradient so aggregates read precisely.

More examples

Rating - headless

Styled SvRating (half stars) plus a custom segmented meter, one bound numeric value with live preview.

Sizes

Every control takes the same three sizes, so a dense toolbar and a roomy form can share components.

<script lang="ts">
  import { SvRating } from '@svgrid/grid'

  let score = $state(1)
</script>

<SvRating value={score} size="sm" />
<SvRating value={score} size="md" />
<SvRating value={score} size="lg" />

In a form

The shared field props behave the same on every editor: label names it, hint explains it, and error plus invalid mark it - which is why a validated form does not need per-component handling.

<script lang="ts">
  import { SvRating } from '@svgrid/grid'

  let score = $state(1)
</script>

<SvRating
  value={score}
  label="Label"
  hint="A short hint"
  required
/>

<SvRating
  value={score}
  label="Label"
  error="Something is wrong"
  invalid
/>

See also

• SvSwitchButton - a simple on/off setting.
• SvRadioGroup - pick one option from a labelled set.
• Buttons & toggles overview - the whole family at a glance.