IconMeter
Discrete icon-row meter for scores and levels — filled, half, or empty slots; not a continuous dial or progress bar.
Base UI
IconMeter paints a score as a row of icons — full, half, or empty — with Base UI meter semantics. Pass value (and optional iconCount); the reading clamps into [0, iconCount], then each slot snaps to empty / half / full paint from the fractional bands below. The default glyph is a star; swap icon for any recolorable SVG component that honors fill.
Reach for IconMeter when the metaphor is discrete icons: ratings, quality pips, favorite counts. Prefer Meter for a continuous horizontal capacity bar, Gauge for a polar dial, and LinearProgress for in-progress or indeterminate work. IconMeter is display-only — do not use it as an interactive rating control.
Highlight paint defaults to the theme primary. Override with highlightColor as any valid CSS color (#hex, named colors, oklch(), var(--*), …). Always name the meter when you hide the visible label (aria-label or aria-labelledby).
When to use
- Discrete scores or levels as filled / half / empty icons
- Read-only ratings, quality pips, or similar icon rows
When not to use
- Continuous capacity on a track → Meter
- Polar dial or needle → Gauge
- In-progress or indeterminate task progress → LinearProgress
- Interactive star rating the user edits → out of scope for IconMeter
Related
- Meter — read-only scalar on a horizontal track
- Gauge — round dial for determinate readings
- LinearProgress — task progress bars
Common examples
Default row
A five-star row with a half fill is the baseline. The visible label mirrors the numeric value unless you pass label or hide it.
Fill thresholds
value is clamped to [0, iconCount], then the fractional part snaps paint into three bands per unit:
- under
0.25→ stay on the floor (empty remainder on that icon) 0.25–under0.75→ half that icon0.75and up → ceil to a full icon
The visible label and assistive valuetext keep the clamped number (for example 0.2 of 5); only the icon paint uses the snapped bands. Out-of-range values clamp — negative → all empty, above iconCount → all full.
Sizes
Use size for dense list rows versus roomier card chrome — icon size, gap, and label scale together.
Highlight color
Pass any CSS color string on highlightColor when the row should match semantic paint — primary, warning, success, danger.
Custom icons
Swap icon for a recolorable SVG component that accepts fill (solid color or half-gradient url). Hearts, pips, or product glyphs work the same way.
Labels
Omit label to show the numeric value. Pass a short word for product copy, or hideLabel with aria-label when the surrounding UI already names the score.
Ask your agent
Add a read-only five-star rating beside this review card — three and a half stars, with the numeric score shown next to the icons.Last updated on