Skip to content

StarRating

Interactive star rating with hover preview, half-star support, keyboard navigation (arrow keys, Home/End), and click-to-toggle.

import { StarRating } from "phoundry-ui";

Interactive

Loading interactive example…

View source
interactive.svelte
<script lang="ts">
import { StarRating } from "phoundry-ui";
let interactive = $state(3);
</script>
<StarRating
rating={interactive}
onchange={(v: number) => {
interactive = v;
}}
/>
<p class="mt-2 text-xs text-txt-tertiary">Rating: {interactive}</p>

Half Stars

Loading interactive example…

View source
half-stars.svelte
<script lang="ts">
import { StarRating } from "phoundry-ui";
let half = $state(3.5);
</script>
<StarRating
rating={half}
allowHalf
onchange={(v: number) => {
half = v;
}}
/>
<p class="mt-2 text-xs text-txt-tertiary">Rating: {half}</p>

Readonly

Loading interactive example…

View source
readonly.svelte
<script lang="ts">
import { StarRating } from "phoundry-ui";
</script>
<div class="flex flex-col gap-2">
<div class="flex items-center gap-3">
<StarRating rating={4} readonly />
<span class="text-xs text-txt-tertiary">4 / 5</span>
</div>
<div class="flex items-center gap-3">
<StarRating rating={2.5} readonly allowHalf />
<span class="text-xs text-txt-tertiary">2.5 / 5</span>
</div>
</div>

Custom max (10 stars)

Loading interactive example…

View source
custom-max-10-stars.svelte
<script lang="ts">
import { StarRating } from "phoundry-ui";
let tenScale = $state(7);
</script>
<p class="mb-2 text-xs text-txt-secondary">
<code>max</code> adjusts star count and <code>aria-valuemax</code>; keyboard
Home/End still jump to 0 / max.
</p>
<StarRating
rating={tenScale}
max={10}
onchange={(v: number) => (tenScale = v)}
/>
<p class="mt-2 text-xs text-txt-tertiary">Value: {tenScale} / 10</p>

Sizes

Loading interactive example…

View source
sizes.svelte
<script lang="ts">
import { StarRating } from "phoundry-ui";
</script>
<div class="flex items-center gap-6">
<div class="flex flex-col items-center gap-1">
<StarRating rating={3} size="xs" readonly />
<span class="text-[10px] text-txt-tertiary">xs</span>
</div>
<div class="flex flex-col items-center gap-1">
<StarRating rating={3} size="sm" readonly />
<span class="text-[10px] text-txt-tertiary">sm</span>
</div>
<div class="flex flex-col items-center gap-1">
<StarRating rating={3} size="md" readonly />
<span class="text-[10px] text-txt-tertiary">md</span>
</div>
<div class="flex flex-col items-center gap-1">
<StarRating rating={3} size="lg" readonly />
<span class="text-[10px] text-txt-tertiary">lg</span>
</div>
</div>

API

From phoundry-ui@0.4.21

NameTypeDefaultDescription
ratingrequirednumber0Current rating value.
readonlybooleanfalseDisable interaction.
size"xs" | "sm" | "md" | "lg"'md'Star size (12/16/20/24px). xs uses tighter padding for dense readonly rows.
maxnumber5Total number of stars.
allowHalfbooleanfalseEnable half-star increments.
onchange(rating: number) => void—Called when the rating changes.
classstring''Additional CSS classes.

Usage tips

  • Click a star to set the rating; click the same star again to reset to 0.
  • With allowHalf, clicking the left half of a star sets a half-star value.
  • Use readonly for display-only ratings (e.g. product reviews, averages).
  • Use size="xs" for dense readonly rows (thumbnail captions, compact table cells); it uses tighter padding than larger sizes.
  • Keyboard: Arrow keys adjust by 1 (or 0.5 with allowHalf), Home = 0, End = max.

CSS styling

.ph-star-rating is the stable identification hook for StarRating. Part selectors and --_ph-* properties are internal. Component CSS is scoped and unlayered; Consumer classes remain additive and utility overrides may lose precedence.

The rating-specific icon scale remains xs 0.75rem, sm 1rem, md 1.25rem, and lg 1.5rem. Rating and keyboard behavior are unchanged.

Keep the shared component stylesheet and a named Theme imported. Decorative motion respects reduced-motion preferences.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.