Hesoyam

Gauge

Circular 0–100 readout. Pair it with a name; the ring is not self-describing.

Sizes

tiny is 20px, small 32px, medium 64px, large 96px. Default is medium.


        

          1
          
          <Gauge size="tiny" :value="50" />
        

          2
          
          <Gauge size="small" :value="50" />
        

          3
          
          <Gauge size="medium" :value="50" />
        

          4
          
          <Gauge size="large" :value="50" />

Value

show-value prints the rounded percent. tiny places the number beside the ring; other sizes draw it in the center.

80
80
100
80
100
80
100

        

          1
          
          <Gauge show-value size="tiny" :value="80" />
        

          2
          
          <Gauge show-value size="small" :value="80" />
        

          3
          
          <Gauge show-value size="medium" :value="80" />
        

          4
          
          <Gauge show-value size="large" :value="100" />

Default color scale

Without colors, the fill steps red → amber → green at 0 / 33 / 66.


        

          1
          
          <Gauge size="small" :value="14" />
        

          2
          
          <Gauge size="small" :value="34" />
        

          3
          
          <Gauge size="small" :value="68" />

Custom color range

Pass a numeric scale. The stroke uses the last key the value has reached.


        

          1
          
          <Gauge
        

          2
          
            size="small"
        

          3
          
            :value="70"
        

          4
          
            :colors="{
        

          5
          
              0: 'var(--ds-pink-100)',
        

          6
          
              50: 'var(--ds-pink-500)',
        

          7
          
              100: 'var(--ds-pink-1000)',
        

          8
          
            }"
        

          9
          
          />

Named colors

primary and secondary pin both arcs instead of using the threshold scale.


        

          1
          
          <Gauge
        

          2
          
            size="medium"
        

          3
          
            :value="50"
        

          4
          
            :colors="{
        

          5
          
              primary: 'var(--ds-blue-700)',
        

          6
          
              secondary: 'var(--ds-blue-300)',
        

          7
          
            }"
        

          8
          
          />

Arc priority

equal sizes both arcs so a 50/50 ratio reads as a split. Default primary grows the filled arc only.

50
50

        

          1
          
          <Gauge
        

          2
          
            arc-priority="equal"
        

          3
          
            show-value
        

          4
          
            size="medium"
        

          5
          
            :value="50"
        

          6
          
            :colors="{
        

          7
          
              primary: 'var(--ds-blue-700)',
        

          8
          
              secondary: 'var(--ds-red-700)',
        

          9
          
            }"
        

          10
          
          />

Indeterminate

Spins the ring while a value is still being computed. value still sets how much of the ring is painted.


        

          1
          
          <Gauge indeterminate size="tiny" :value="25" />
        

          2
          
          <Gauge indeterminate size="small" :value="25" />
        

          3
          
          <Gauge indeterminate size="medium" :value="25" />
        

          4
          
          <Gauge indeterminate size="large" :value="25" />

Overlay

Default slot sits in the center. Use it for an icon, not a unit string.


        

          1
          
          <Gauge size="medium" :value="72">
        

          2
          
            <Icon :icon="FlashIcon" :size="18" class="text-[var(--ds-gray-1000)]" />
        

          3
          
          </Gauge>

Best practices

  • Gauge is a 0–100 ratio against a known max — quota, cache hit rate, uptime. Known-total task progress belongs on Progress. Binary state belongs on Badge or Status Dot.
  • arc-priority="equal" for true ratios so 50% is half the ring. Leave the default primary when only the filled share matters.
  • Reuse product thresholds in colors. Do not invent gauge-only breakpoints.
  • Name the metric next to the ring. show-value prints the number only — never a % or unit inside the slot.
  • Pair indeterminate with copy such as «Calculating usage…» so a spinning ring is not read as zero.
  • The control already sets role="progressbar" and value ARIA. Do not override those; color is not enough without text.