ScoreRing
score-ringDisplays a numeric score and grade inside a color-coded radial gauge.
Usage
Basic usage
value drive ring progress and center number, the default score is 100, and the A-F level word is displayed.
<ScoreRing value={82} label="Quality Points" />Grade bands
The default A-F grade is automatically selected according to the score: A excellent / B good / C passing / F failing.
<>
<ScoreRing value={95} label="Quality Points" />
<ScoreRing value={82} label="Quality Points" />
<ScoreRing value={68} label="Quality Points" />
<ScoreRing value={42} label="Quality Points" />
</>Size and ring width
size controls the diameter, thickness controls the ring width; for small sizes, showGrade={false} only leaves numbers.
<>
<ScoreRing value={88} size={48} thickness={5} showGrade={false} />
<ScoreRing value={88} size={96} thickness={8} label="Quality Points" />
<ScoreRing value={88} size={128} thickness={12} label="Quality Score" />
</>When to use
Use ScoreRing to present a quality, health, or rating score as a circular gauge with automatic A-F grade coloring. Use [Meter] or [Progress] for linear progress and capacity, or Sparkline for trends. Its SVG dasharray rendering is compatible with React Server Components.
Import
import { ScoreRing, resolveGrade, DEFAULT_GRADES } from "@hulianui/ui"Props
Grade = { min: number; label: string; tone?: string }, where min is the **lowest score
(inclusive)** that lands in the band, label is the band's caption, and tone takes either a
semantic color name ("success" / "warning" / "danger" / "chart-2" and so on) or any CSS
color value (#hex, var(--color-success)). Both are typed string and both are accepted.
| Name | Type | Default | Description |
|---|---|---|---|
| value* | number | - | Current score. |
| max | number | 100 | Maximum score. |
| grades | Grade[] | - | Grade bands; omission uses DEFAULT_GRADES for A-F. |
| size | number | 96 | Diameter in pixels. |
| thickness | number | 8 | Ring thickness in pixels. |
| showGrade | boolean | true | Shows the grade letter. |
| className | string | - | Custom class name. |
Slots
| Slot | Type | Description |
|---|---|---|
| label | ReactNode | Secondary center label, such as "Quality score". |
Pitfalls
- `resolveGrade(value, grades)` determines the grade color. It takes two arguments and
there is no `max`: max is a prop this component uses to draw the arc, not a parameter of
the function. Before 0.56.1 this section claimed three arguments, and following it with
resolveGrade(score, 100, myGrades) passes 100 where grades belongs.
- The default `DEFAULT_GRADES` has five bands but only three colors (A/B are both success,
C/D are both warning). Pass your own grades when every band needs its own color.
- A band without `tone` falls back to the component's default color, not to transparent.
Give it an explicit color when a band should not be tinted.
Related
Sparkline · ImageViewer · LiveProductCard · DiffStat · Badge · Dot
Playground
<ScoreRing value={82} size={96} thickness={8} label="Quality Points" />