A Linear Gauge presents a single data point within a predefined range along a scale. The data is represented by a bar indicating the value.
Simple Linear Gauge
To create a Linear Gauge, use the <AgGauge />
component with the type linear-gauge
.
const [options, setOptions] = useState({
type: 'linear-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.
Horizontal Linear Gauge
To create a Horizontal Linear Gauge, set direction: 'horizontal'
.
{
direction: 'horizontal',
}
Customisation
Thickness
{
thickness: 100;
bar: {
thickness: 50;
}
}
In the above configuration:
- The thickness of the scale is specified as 100 pixels.
- The thickness of the bar is specified as 50 pixels.
- It is also possible to use
thicknessRatio
to specify the width of the bar as a proportion of the scale.
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.
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: 'before',
fill: 'white',
strokeWidth: 2,
spacing: 8,
},
{
value: 75,
placement: 'after',
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 - eitherbefore
,after
, 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
.
Bullet Series
The Linear Gauge is used to create a Bullet Series.
{
type: "linear-gauge",
//...
thickness: 50,
value: 50,
scale: {
min: 0,
max: 100,
fills: [{ color: "#A6A6A5" }, { color: "#BFBFBF" }, { color: "#D9D9D9" }],
fillMode: "discrete",
},
bar: {
thickness: 25,
fill: "black",
},
targets: [
{
value: 60,
shape: "line",
size: 20,
placement: "middle",
strokeWidth: 2
},
],
}
In the above configuration:
- The bar
thickness
is set to less that the gauge thickness. - The scale has a number of
fills
and afillMode
ofdiscrete
. - The target has
line
shape with astrokeWidth
of 2 and is placed in themiddle
.