Score Ring

A circular score meter whose color blends from a start to an end color.

Overview

ScoreRing draws a progress ring for a score and shows the number in the middle. The stroke color is mixed between fromColor and toColor by the score, so 0 is red and 100 is green unless you pass other colors.

It is a role="meter". Use Progress for task completion and ScoreRing for a quality or rating score.

Preview

0

Customize

Value
0
Size
From Color#ef4444
To Color#22c55e
Show Value

Installation

Add the component with the CLI. It copies the files in and installs anything they depend on.

npx vinyaas add score-ring

Usage

import { ScoreRing } from "@/components/ui/score-ring";

export function Performance() {
  return <ScoreRing value={86} label="Performance score" />;
}

Examples

Default

The ring color blends from red at 0 to green at 100, so low scores read as warnings.

12
48
74
96

Sizes

xs, sm, default, and lg scale the ring, stroke, and score text together.

82
82
82
82

Custom colors

fromColor is the color at 0 and toColor is the color at max. Use any CSS color, including theme variables.

35
80
65

Custom content and range

max changes the full-ring score. children replaces the number, and showValue={false} hides it.

4.2

In practice

An audit card shows four category scores. The ring color alone separates healthy scores from failing ones.

Site audit
92

Performance

78

Accessibility

54

Best practices

31

SEO

API

Other attributes for the underlying element are passed through.

NameTypeDefaultDescription
valuenumber—Score from 0 to max. Values outside the range are clamped.
maxnumber100Score that fills the whole ring.
size"xs" | "sm" | "default" | "lg""default"Ring diameter: 32px, 48px, 64px, or 96px.
fromColorstring"var(--color-red-500, #ef4444)"Ring color at a score of 0. Any CSS color.
toColorstring"var(--color-green-500, #22c55e)"Ring color at the maximum score. Any CSS color.
showValuebooleantrueShow the rounded score in the middle of the ring.
childrenReactNode—Replaces the score text in the middle of the ring.
labelstring—Accessible name for the meter, such as Performance score.

Accessibility

The ring is a role="meter" with aria-valuenow, aria-valuemin, and aria-valuemax. The SVG is hidden from assistive technology.

  • Pass label so the meter has an accessible name.
  • Do not rely on color alone; keep the number visible or put the score in nearby text.
  • The fill animation is disabled for reduced motion.