Ring chart

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

Each item needs a label, a value and the maxValue that fills its ring. Rings are drawn from the inside out, in the order of data.

<script setup lang="ts">
import { Ring, RingCenter, RingChart } from "@/components/ui/charts";

const data = [
  { label: "Running", maxValue: 30, value: 24 },
  { label: "Cycling", maxValue: 60, value: 41 },
  { label: "Swimming", maxValue: 20, value: 9 },
];
</script>

<template>
  <RingChart
    ariaLabel="Training hours against monthly goals"
    :data="data"
    :size="240"
  >
    <Ring v-for="(item, index) in data" :key="item.label" :index="index" />
    <RingCenter default-label="Hours" />
  </RingChart>
</template>

Anatomy

The rings come from data, the first item innermost. Everything else is a child you add: a grid behind the rings, their names, a number in the middle.

<RingChart :data="data" :end-angle="Math.PI / 2" :start-angle="-Math.PI">
  <RingGrid />
  <Ring :index="0" />
  <Ring :index="1" line-cap="butt" />
  <RingLabels color-by-ring />
  <RingCenter default-label="Steps" />
</RingChart>

• RingChart: Draws one ring per item of data, each filled to value / maxValue of its track.
• RingGrid: Spokes across the rings at progress ticks, labeled outside the arc. Place it before the rings.
• Ring: Overrides one ring by index: its color, lineCap or animate.
• RingLabels: Each ring's name, set just before the point where it starts.
• RingCenter: The sum of every value at rest, the hovered ring's value and label on hover.

Arcs and half rings

startAngle and endAngle set the sweep in radians, clockwise from 12 o'clock. The default is a full turn starting at 9 o'clock. -(3 * Math.PI) / 4 to (3 * Math.PI) / 4 leaves the bottom quarter open, as in this example.

Pass lineCap="butt" to a <Ring> for square ends.

Progress grid and labels

<RingGrid /> draws a spoke across the rings at each quarter of the way to maxValue and labels it past the outer ring. :ticks="[0, 0.5, 1]" picks your own fractions, and tickFormat writes their labels.

<RingLabels /> names each ring just before its start, so it needs a gap in the circle: a three-quarter arc or a half ring. With a grid, the chart keeps 32 px around the rings for the labels instead of 8.

Different targets

Rings don't have to share a target. Give each item its own maxValue and the fills stay comparable as percentages while the center adds up the raw values.

Format that total with formatOptions (any Intl.NumberFormat options, such as compact currency), prefix and suffix.

With a legend

A hovered ring grows by 3% and the others fade. hoveredIndex and onHoverChange make that hover controlled, so a <Legend> given the same state lights up the matching ring, and the ring lights up its row.

LegendProgress in a row draws a bar from the item's value and maxValue, the same numbers the ring uses.

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.

Ring geometry is three props in pixels: strokeWidth (12), ringGap (6) and baseInnerRadius (60). When they don't fit in size, every ring scales down by the same factor. Leave size out and the chart takes its container's width and stays square.

For the hovered state of the center, give RingCenter a function as its child. It receives value, label and the ring's data, so it can show progress against that ring's own maxValue. At rest the total still shows.

<RingCenter default-label="Booked">
  <template #default="{ data, label, value }">
    <div class="text-center">
      <div class="font-semibold text-2xl tabular-nums">
        {{ Math.round((value / data.maxValue) * 100) }}%
      </div>
      <div class="text-muted-foreground text-xs">{{ label }}</div>
    </div>
  </template>
</RingCenter>

Where a part renders content of its own, you pass it in. In Vue:

• RingCenter: <template #default="{ value, label, isHovered, data }">

Loading state

The ring chart has no loading state of its own. While the numbers load, render a round Skeleton at the chart's size in its place, so the card doesn't jump when the rings mount.

Animation

Each track scales up from the center, one ring after the next, and its fill sweeps round from the start angle. enterTransition takes a motion-style transition (a 1.1 s tween unless you pass one), and enterStaggerScale stretches the delay between rings: 0 starts them together.

:animate="false" on a Ring draws that ring filled from the first frame. With reduced motion turned on, the fills appear at their values without the 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.

Rings take --chart-1 to --chart-5 in order, then repeat. Set color on a data item or on its <Ring> to choose one.

The empty tracks are your theme's --border. RingGrid draws its spokes in --chart-foreground at 20% opacity, and its labels, like RingLabels, in --chart-label.

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

Accessibility

The chart is an image named by ariaLabel ("Ring chart" by default). Rings show progress but not what it measures, so put the goal in the name or in ariaDescription.

Keyboard focus behaves like hover: the focused ring grows, the others fade, and RingCenter shows its value and label.

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).

RingChart

Ring

RingCenter

RingGrid

RingLabels