Gauge

Installation

The command adds the example above to components/charts/ and, the first time, the chart kit to components/ui/charts/. Both are source files in your project from then on: read them, change them, delete what you don't use.

Usage

value is the fill, from 0 to 100. The number in the middle is a separate prop, centerValue, so a gauge filled to 66% can show revenue. Leave it out and there's no label.

<script setup lang="ts">
import { Gauge } from "@/components/ui/charts";
</script>

<template>
  <Gauge
    ariaLabel="Storage used"
    :center-value="72"
    default-label="Storage used"
    :inactive-fill-opacity="0.4"
    suffix="%"
    :value="72"
  />
</template>

Anatomy

The gauge is one component and every layer is a prop. The arc-only layers (ruler, needle, zones, sector, progress ring, dots, glow, center disc) claim room from the outside in, and the track shrinks to fit them.

<Gauge
  arc-style="solid"
  :center-value="78"
  default-label="Disk"
  needle="triangle"
  ruler
  suffix="%"
  :value="78"
  :zones="zones"
/>

• Gauge: The track, the fill, the label and any dial layers you turn on.

Arcs and notches

startAngle and endAngle are in degrees, with 0 pointing right and angles running clockwise. The default 135 to 405 opens at the bottom, and 180 to 360 is the top half.

totalNotches (40), spacing (the share of the track left as gaps, 25%) and notchCornerRadius shape the notches. useGradient shades the lit ones across --chart-1 to --chart-5, or between the two colors of activeGradient.

Linear gauges

orientation="linear" lays the notches along a straight track that fills its container. labelPlacement puts the label on any side of it and labelAlign at its start, center or end. linearHeight (24 px) sets the thickness.

The dial layers below are for arcs only. A linear gauge ignores them.

Notches, a solid arc or no track

arcStyle="solid" swaps the notches for one rounded stroke, arcThickness thick. "none" drops the track altogether and leaves the value to a sector, a progress ring or dots.

Rulers

ruler adds a scale of ticks inside the track that brightens up to the value. Pass options to move it outside with position, set ticks and majorEvery, and number it with labels: every major tick, the two "ends", or your own min, max and format.

Needles

needle takes a variant, "line", "gradient", "triangle" or "polygon", or options. length is a fraction of the reach, and tip ends it inside the track, at its outer edge or past the outermost layer.

Zones

zones marks ranges on the 0 to 100 scale, a red stretch past 85 for instance. By default each is a thin band around the track. zoneDisplay="fill" colors the fill itself where it crosses a zone, and "both" does both.

Sectors, rings and dots

sector fills a wedge from the start to the value, with a conic or radial gradient or a flat color, which can be a pattern. progressRing adds a thin ring around the track, dots rings of dots that light up to the value, and glow a bloom on the fill.

centerDisc puts a ringed disc behind the label. Each takes true for its defaults or an options object.

Customization

The kit is in your project, in components/ui/charts/: your framework's components over a shared core/. Change a default there and every chart picks it up.

class goes on the chart's container, so size and spacing are utility classes.

Children go into a hidden <defs>. Put a PatternLines or a gradient there and point activeFill, inactiveFill or a sector's color at it with url(#id). The ids are global to the page, so give each gauge its own.

<Gauge
  active-fill="url(#quota-stripes)"
  :inactive-fill-opacity="0.4"
  :value="64"
>
  <PatternLines
    :height="6"
    id="quota-stripes"
    :orientation="['diagonal']"
    stroke="var(--chart-1)"
    :stroke-width="1.5"
    :width="6"
  />
</Gauge>

Loading state

There's no loading state. Render the gauge at :value="0" until the reading arrives, and the fill sweeps up from zero when it does.

Animation

On mount the track fades in, then the fill sweeps up from zero on a spring with no bounce, lighting each notch as it passes. The needle, sector, ring and dots ride the same sweep.

A new value carries on from wherever the fill is, at the speed it already has, so a gauge fed every second never snaps back. enterTransition replaces the spring ({ type: "spring", visualDuration: 0.9, bounce: 0 }), and enterStaggerScale the pause before the sweep starts.

With reduced motion turned on, the gauge draws at its value with no sweep.

Theming

Every color in the kit is one of your theme's tokens or a mix of them, except --chart-positive, a fixed green. A preset or the .dark class restyles the chart, and overriding a token in your CSS changes it everywhere.

Lit notches are --chart-1 and unlit ones your theme's --border at 80% opacity, unless you set activeFill and inactiveFill. With useGradient, the fill runs through the five chart colors.

Needles, rulers and the center disc's ring are drawn in --foreground, and a progress ring's remainder in --muted-foreground. Each has a prop to change it.

:root {
  --chart-label: var(--foreground);
}

Accessibility

A gauge is one image with nothing to step through, so it takes no tab stop. It's announced by its name, "Gauge: 72%" unless you pass ariaLabel.

Once you name it, the reading moves to ariaDescription, so a screen reader still says the value. Pass your own description to say more, such as the limit.

API reference

Vue takes the same props as React, in camelCase or kebab-case, with class for className. Render props are scoped slots (#content), and callbacks such as onHoverChange can be written as listeners (@hover-change).

Gauge