A headless React hook for building gauge charts. You bring the styles, we bring the math that powers your chart!
Code for the examples above 👆 https://i19w7.csb.app/
yarn add use-gauge
🚨 Beware that this API is very much in flux! Breaking changes will occur, but I'll update these docs and the Codesandbox accordingly 🚨
In your React project, import the useGauge
hook and invoke it with the following parameters.
const {
ticks,
valueToAngle,
angleToValue,
getTickProps,
getLabelProps,
getArcProps,
getNeedleProps,
getSVGProps,
} = useGauge({
startAngle: 90, // The bottom of the gauge is considered 90 degrees, so this means 90 degrees FROM 90, so 180.
endAngle: 270, // And this means 270 degrees FROM 90, so 360.
numTicks, // the number of ticks to display between the min and max values
diameter, // diameter of the gauge itself
domain: [minValue, maxValue], // Min and max values for your gauge. *Please* use a min that's smaller than the max :)
});
If you want to skip ahead and see a fully baked implementation of this hook, check out the example playground.
Otherwise, here's a brief explanation of how these returned values work.
Please be sure to apply these props to your SVG element, as it's responsible for programatically updating the height, width, and viewBox of the element as a function of the diameter
you provide.
<svg {...getSVGProps()}></svg>
ticks
is an array of evenly spaced angles (represented as numbers) that's calculated from the numTicks
, startAngle,
and endAngle
argument.
You can create visual tick marks on the SVG by mapping over this array and passing each angle (along with a length
argument) to the getTickProps
function accordingly.
Additionally, you can render text labels for tick mark by invoking the getLabelProps
on the given angle (along wiht an offset
argument that determines how far the label sits from the tick).
Note that you'll need to convert the given angle to its "value" counterpart (as minValue and maxValue are the domain of our dataset) by invoking the angleToValue
function with the given angle as an argument.
{
ticks.map((angle) => {
return (
<React.Fragment key={`tick-group-${angle}`}>
<line
stroke={tickColor}
{...getTickProps({ angle, length: tickLength })}
/>
<text
className="text-sm fill-gray-500 font-medium"
{...getLabelProps({ angle, offset: 20 })}
>
{angleToValue(angle)}
</text>
</React.Fragment>
);
});
}
This function allows you to render arcs of arbitrary length, as expressed by a start angle and end angle. A common use-case might be to have two arcs: one as a "background", and another that represents the progress of the gauge.
You can calculate progress in this scenario by converting your numerical value to its angle counterpart with the valueToAngle
function.
// Background
<path
{...getArcProps({ offset, startAngle: 90, endAngle: 270 })}
className="stroke-gray-100"
strokeLinecap="round"
strokeWidth={24}
/>
// Progress
<path
{...getArcProps({
offset,
startAngle,
endAngle: valueToAngle(value),
})}
className="stroke-blue-600"
strokeLinecap="round"
strokeWidth={24}
/>
Last but not least, this function helps you draw a needle shape on your gauge. Specifically, it returns the bits you need to draw: A) the "tip" of the needle (i.e., the small circle at the top), B) the "base" of the needle (i.e., the bigger circle at the bottom), and C) the "body" of the needle (i.e., the polyline that connects these two circles).
Warning: this API is janky. There's got to be a better way of handling this, but again, this is what worked for my initial use case 🤷🏻♂️
const { tip, base, points } = getNeedleProps({
value,
baseRadius: 12,
tipRadius: 8,
});
<g id="needle">
<circle className="fill-gray-300" {...base} r={24} />
<circle fill={needleColor} {...base} />
<circle fill={needleColor} {...tip} />
<polyline fill={needleColor} points={points} />
<circle className="fill-white" {...base} r={4} />
</g>;
From the project root, run yarn start
. This will run tsdx
in watch mode, and will re-compile the code every time you save.
In a different terminal window, cd
into the /example
directory and run yarn start
. This will boot up Parcel and open a web server at http://localhost:1234. All of your changes to the hook source code will (eventually) propagate to Parcel's hot-reloading server.