Forms

Rating

Star rating control with bindable numeric value, optional half-star precision, and a non-interactive readonly display mode.

import { Rating } from '@lostgradient/cinder/rating';
formselection
01

Overview

Star rating control with bindable numeric value, optional half-star precision, and a non-interactive readonly display mode.

Usage

svelte 
<script lang="ts">
  import Rating from '@lostgradient/cinder/rating';
  let score = $state(0);
</script>

<Rating id="rating" bind:value={score} label="Quality" />
Live preview
02

When to use

Use when
  • Letting the user score something on a small ordinal scale such as 1-5 stars.
  • Displaying an existing rating in readonly mode alongside a count or average.
Avoid when
  • Picking a value from a numeric continuum — use slider instead.
  • Capturing a binary preference — use toggle or checkbox.
03

Examples

Basic rating

Five-star rating with whole-star precision and keyboard navigation.

Half-star precision

Five-star rating with half-star steps for finer-grained scores.

Readonly display

Non-interactive readonly rating shown alongside a review count.

04

Props

Props for rating
Name Type Default Required Bindable Description
id text req Stable id used as the radio-group id prefix and as the hidden input id.
value number 0 bind Bindable rating value. 0 represents an unrated state. External values are clamped into [0, count] and snapped to the nearest precision step. No write-back normalization. The bound prop reflects exactly what the consumer set — it is NOT mutated back to the clamped/snapped value. The displayed and submitted value is normalized via $derived, but the binding itself is left untouched. This is intentional: the consumer owns the source of truth, and silent mutation of a bound prop is a surprising side-effect.
count number 5 Number of rating slots. Normalized to an integer in [1, 10]; non-finite or out-of-range values fall back to 5.
precision 'whole' | 'half' 'whole' Precision of each step. Defaults to 'whole'.
label text Visible group label rendered above the rating.
hideLabel boolean false Visually hide the rendered label while keeping it programmatically associated.
description text Optional description text rendered below the rating.
error text Optional error message; sets aria-invalid="true" on the rating group.
disabled boolean Disable every rating control and the hidden input.
readonly boolean false Render a non-interactive display with an accessible text equivalent.
required boolean Mark the group as required for assistive technology.
name text Form-control name applied to the hidden <input> that submits with the form.
onchange (value: number) => void Fires only for user-initiated committed value changes (click, arrow keys, Space/Enter). Never fires for hover preview or external prop synchronization.