DonutGauge

Every example on this page is live, drawn by the library's Storybook, where you can also change its props and see the result.

A ring filled clockwise from twelve o'clock to show a ratio, with the ratio written in its middle.

The ring stays round in any box: it is drawn as large as the box holds and centered, in the widget and in its previews alike. A ratio of nothing or less leaves the ring empty, and one of the whole or more fills it.

The middle reads as the two numbers, rounded so a ratio worked out from other figures never prints as a long decimal. format="percent" writes the share they make instead ("82%"), and a function writes any other text, such as a count of days left.

Import

import { DonutGauge } from "~lib/charts/donut-gauge";

Props

Name	Type	Required	Default	Description
numerator	number	Yes	N/A	The current value
denominator	number	Yes	N/A	The maximum value
pattern	PatternType	No	"solid"	Fill pattern of the filled arc
width	number | string	No	300	Chart width
height	number | string	No	300	Chart height
format	"fraction" | "percent" | (numerator: number, denominator: number) => string	No	"fraction"	How the middle of the ring reads

PatternType: "solid" | "diagonal" | "dots" | "crosshatch"

Examples

Basic Gauge

A donut showing 50 out of 100:

Open With Points in Storybook

In a Wide Box

Open Wide Box in Storybook

Writing the Reading

By default the middle reads as the two numbers, rounded to be short while a number below one keeps the digits that tell it from nothing, so two and two thirds of four reads "2.7 / 4":

Open Rounded in Storybook

Set format="percent" to write the share as a whole percentage:

Open Percent in Storybook

Pass a function to write anything else. It gets the numerator and the denominator:

Open Custom Format in Storybook

<DonutGauge
  numerator={daysGone}
  denominator={daysInTerm}
  format={(gone, total) => `${total - gone} days left`}
/>

See Also

• BarIndicator - Horizontal bar for displaying ratios
• PieChart - Pie chart with patterns