A Radial Gauge presents a single data point within a predefined range using a circular scale. The data is represented by a needle or bar indicating the value.
Simple Radial Gauge
To create a Radial Gauge, use the createGauge
API with the type radial-gauge
.
const [options, setOptions] = useState({
type: 'radial-gauge',
value: 80,
scale: {
min: 0,
max: 100,
},
});
return (
<AgGauge options={options} />
);
In this configuration:
value
is the value displayed by the gauge.scale.min
defines the minimum value of the scale.scale.max
defines the maximum value of the scale.- The data is represented by a coloured bar displayed over a grey scale.
Customisation
Needle / Bar
It is possible to display the data value using a bar, a needle or both. These are both rendered over the scale.
{
needle: {
enabled: true,
},
bar: {
enabled: false,
},
}
In the above example, note that:
- When the needle is enabled, the label is not shown.
- When the bar is disabled, the scale defaults to showing the gradient colour instead of the solid grey.
For customisation of both the bar and needle, see below or the API Reference.
Labels
Up to two inner labels can be configured with the label
and secondaryLabel
properties.
{
label: {
formatter({ value }) {
return `${value.toFixed(0)}%`;
},
},
secondaryLabel: {
text: 'Test Score',
},
scale: {
label: {
enabled: false,
},
},
}
In this configuration:
- The first label uses a
formatter
to format the value. - The second label displays a fixed
text
string. This option is only available for inner labels. - The scale labels are hidden using the
scale.label.enabled
option. See the API Reference for more details about customising the scale label style and interval.
Segmentation
To split the gauge into segments, set segmentation.enabled
to true
.
{
segmentation: {
enabled: true,
interval: {
count: 4
},
spacing: 2,
},
}
In this configuration:
segmentation.interval
specifies how the gauge is segmented. Available options are:step
- segments the gauge at a fixed interval.count
- segments the gauge a fixed number of times.values
- segments the gauge at specific scale values.
spacing
defines the spacing between each segment.
Corner Radius
{
cornerRadius: 99,
cornerMode: 'container',
}
In this configuration:
cornerRadius
specifies the amount of curvature applied to each corner.cornerMode
can be set tocontainer
to apply rounded corners only to the start and end of the gauge, oritem
for all visual items within the gauge.
Start and End Angles
The startAngle
and endAngle
properties can be used to customise the start and end position of the gauge.
{
startAngle: 225,
endAngle: 495,
}
- Angles are calculated clockwise, starting from the top of the gauge.
endAngle
must be greater thanstartAngle
.
Colour Options
Single Colour
Both the bar and scale can be displayed using a solid fill.
{
scale: {
fill: '#f5f6fa',
},
bar: {
fill: '#4cd137',
},
}
Multiple Colours
Multiple colours can be specified using the fills
property.
{
bar: {
fills: [{ color: '#00a8ff' }, { color: '#9c88ff' }, { color: '#e84118' }],
fillMode: 'discrete',
},
}
In this configuration:
fills
specifies an array of colours to use to fill the bar.fillMode
can be set tocontinuous
for a gradient, ordiscrete
to use blocks of solid colours.
The default behaviour is to space out the colours evenly. This can be customised by using colour stops.
Colour Stops
{
bar: {
fills: [
{ color: '#E84118', stop: 35 },
{ color: '#FBC531', stop: 45 },
{ color: '#4CD137', stop: 55 },
{ color: '#FBC531', stop: 65 },
{ color: '#E84118' },
],
fillMode: 'discrete',
},
}
In this configuration:
- Each colour stops at the
stop
value, and the next colour begins at that point. - If no
stop
is provided, the fills will be distributed equally. - The last colour is used until the end of the scale or bar.
- Both
discrete
andcontinuous
modes can be used with colour stops.
Targets
Gauges often display targets or thresholds to provide context to the displayed data value. These can be added using the targets
configuration array.
{
targets: [
{
value: 70,
text: 'Average',
},
],
}
In this configuration:
value
is the position for the target marker.text
is an optional string for the target label.
Customisation
{
targets: [
{
value: 30,
shape: 'triangle',
placement: 'outside',
fill: 'white',
strokeWidth: 2,
spacing: 8,
},
{
value: 75,
placement: 'inside',
shape: 'triangle',
fill: 'white',
strokeWidth: 2,
spacing: 8,
},
{
value: 90,
placement: 'middle',
shape: 'circle',
fill: 'white',
strokeWidth: 2,
spacing: 8,
},
],
}
In this configuration:
shape
is a marker shape.placement
indicates the relative placement to the gauge - eitherinside
,outside
, ormiddle
.size
is the size of the marker, in pixels.spacing
is spacing from the edge of the gauge to the marker. Ignored whenplacement
ismiddle
.