gauge
Overview
gauge is used to create gauge charts, which are common visualization charts used to display data progress, proportions, or comparisons.
Typical use cases:
- Business metrics: sales achievement rate, user growth progress;
- System monitoring: CPU/memory usage, disk capacity warnings;
- Device gauges: vehicle speedometer, temperature gauge simulation.
import { Chart } from '@antv/g2';
const chart = new Chart({
container: 'container',
});
chart.options({
type: 'gauge', // Set the chart type to gauge
data: {
value: {
target: 120, // Target value of the gauge
total: 400, // Total value of the gauge
name: 'score', // Name of the gauge data
},
},
});
chart.render();
Options
| Property | Description | Type | Default | Required |
|---|---|---|---|---|
| data | Define the gauge values, target values and category information, driving pointer position, color mapping and multi-gauge facet display through data binding | data | - | ✓ |
| encode | Configure visual channels for gauge marks, including x, y, color, etc., to specify the relationship between visual element properties and data |
encode | - | |
| scale | Configure scales for gauge marks, including y, size, etc. |
scale | - | |
| style | Configure graphic styles and label styles | style | - |
data
data defines the gauge values, target values and category information, driving pointer position, color mapping and multi-gauge facet display through data binding.
| Property | Description | Type | Default | Required |
|---|---|---|---|---|
| target | Set the target value of the gauge pointer | number |
- | |
| total | Set the maximum range value of the gauge scale | number |
- | |
| percent | Set the percentage pointed by the gauge pointer (when percent is configured, target and total values will be invalid, please set thresholds in a reasonable range, otherwise it will cause rendering errors) |
number |
- | |
| thresholds | Set the gauge scale threshold intervals | number[] |
- |
For more data configuration, you can check the data introduction page.
encode
Configure visual channels for gauge marks, which define the mapping relationship between data fields and visual properties. This is an important configuration that determines how data is transformed into visual representation.
| Property | Description | Type | Default | Required |
|---|---|---|---|---|
| x | Bind the x property channel of gauge marks, usually a time or ordinal name field in data |
encode | 'x' |
|
| y | Bind the y property channel of gauge marks, usually a numeric or array field in data |
encode | 'y' |
|
| color | Bind the color property channel of gauge marks. If data fields are mapped to color channels, data will be grouped and split into multiple regions with different colors |
encode | 'color' |
For more encode configuration, you can check the encode introduction page.
scale
scale is used to define how data maps to visual properties (such as color, size, shape, etc.).
| Property | Description | Type | Default | Required |
|---|---|---|---|---|
| y | Define the mapping rules from data fields to Y-axis visual positions | scale | {domain: [0, percent ? 1 : total]} |
|
| color | Define the color mapping rules for gauge scales | scale | {range: ['#30BF78', '#D0D0D0']} |
color
The color distribution is related to the data in data. Colors here can be set as gradients for configuring gradient gauge charts.
- With only
targetorpercent, thecolorparameterrangecan consist of two color parameters. On the gauge scale, these two colors will divide the gauge scale into two segments
import { Chart } from '@antv/g2';
const chart = new Chart({
container: 'container',
});
chart.options({
type: 'gauge',
data: {
value: {
target: 120,
total: 400,
name: 'score',
},
},
scale: {
color: { range: ['#FAAD14', 'green'] },
},
});
chart.render();
- When
thresholdsis set, the colors in thecolorparameterrangeshould match the length ofthresholds. The gauge scale will be segmented by the values inthresholdsand filled with colors from the corresponding positions in thescaleparametercolor
import { Chart } from '@antv/g2';
const chart = new Chart({
container: 'container',
});
chart.options({
type: 'gauge',
data: {
value: {
target: 120,
total: 400,
name: 'score',
thresholds: [100, 200, 400],
},
},
scale: {
color: { range: ['#F4664A', '#FAAD14', 'green'] },
},
});
chart.render();
For more scale configuration, you can check the scale introduction page.
style
style is used to set the appearance of chart elements, including fill colors, border styles, shadow effects, etc.
| Property | Description | Type | Default | Required |
|---|---|---|---|---|
| arc | Configure the style of gauge arc | arc | See arc | |
| pin | Configure the style of gauge pointer axis | pin | See pin | |
| pointer | Configure the style of gauge pointer | pointer | See pointer | |
| text | Configure the style of gauge center text | text | See text |
Composite graphic marks need to be distinguished by different prefixes to configure graphics.
arc
Configure gauge arc styles through the arc prefix.
| Property | Description | Type | Default | Required |
|---|---|---|---|---|
| arcShape | Gauge arc shape | 'rect' |'hollow'|'round' |
'rect' |
|
| arcFill | Gauge arc fill color | string | (datum, index, data) => string | - | |
| arcFillOpacity | Gauge arc fill opacity | number | (datum, index, data) => number | - | |
| arcStroke | Gauge arc stroke color | string | (datum, index, data) => string | - | |
| arcStrokeOpacity | Gauge arc stroke opacity | number | (datum, index, data) => number | - | |
| arcLineHeight | Gauge arc line height | number | (datum, index, data) => number | - | |
| arcLineWidth | Gauge arc stroke width | number | (datum, index, data) => number | - | |
| arcLineDash | Gauge arc dash configuration | [number,number] | (datum, index, data) => [number , number] | - | |
| arcOpacity | Gauge arc overall opacity | number | (datum, index, data) => number | - | |
| arcShadowColor | Gauge arc shadow color | string | (datum, index, data) => string | - | |
| arcShadowBlur | Gauge arc shadow blur factor | number | (datum, index, data) => number | - | |
| arcShadowOffsetX | Gauge arc shadow horizontal offset | number | (datum, index, data) => number | - | |
| arcShadowOffsetY | Gauge arc shadow vertical offset | number | (datum, index, data) => number | - | |
| arcCursor | Gauge arc mouse cursor style | string | (datum, index, data) => string | default |
pin
Configure gauge pointer axis styles through the pin prefix.
| Property | Description | Type | Default | Required |
|---|---|---|---|---|
| pinR | Gauge pointer axis radius size | number | (datum, index, data) => number | 10 |
|
| pinFill | Gauge pointer axis fill color | string | (datum, index, data) => string | '#fff' |
|
| pinFillOpacity | Gauge pointer axis fill opacity | number | (datum, index, data) => number | - | |
| pinStroke | Gauge pointer axis stroke color | string | (datum, index, data) => string | - | |
| pinStrokeOpacity | Gauge pointer axis stroke opacity | number | (datum, index, data) => number | - | |
| pinLineHeight | Gauge pointer axis line height | number | (datum, index, data) => number | - | |
| pinLineWidth | Gauge pointer axis stroke width | number | (datum, index, data) => number | - | |
| pinLineDash | Gauge pointer axis dash configuration | [number,number] | (datum, index, data) => [number , number] | - | |
| pinOpacity | Gauge pointer axis overall opacity | number | (datum, index, data) => number | - | |
| pinShadowColor | Gauge pointer axis shadow color | string | (datum, index, data) => string | - | |
| pinShadowBlur | Gauge pointer axis shadow blur factor | number | (datum, index, data) => number | - | |
| pinShadowOffsetX | Gauge pointer axis shadow horizontal offset | number | (datum, index, data) => number | - | |
| pinShadowOffsetY | Gauge pointer axis shadow vertical offset | number | (datum, index, data) => number | - | |
| pinCursor | Gauge pointer axis mouse cursor style | string | (datum, index, data) => string | default |
pointer
Configure gauge pointer styles through the pointer prefix.
| Property | Description | Type | Default | Required |
|---|---|---|---|---|
| pointerShape | Gauge pointer shape | 'line' |(points, value, coordinate, theme) => DisplayObject |
'line' |
|
| pointerStroke | Gauge pointer stroke color | string | (datum, index, data) => string | - | |
| pointerStrokeOpacity | Gauge pointer stroke opacity | number | (datum, index, data) => number | - | |
| pointerLineWidth | Gauge pointer line width | number | (datum, index, data) => number | - | |
| pointerLineDash | Gauge pointer dash configuration | [number,number] | (datum, index, data) => [number , number] | - | |
| pointerOpacity | Gauge pointer overall opacity | number | (datum, index, data) => number | - | |
| pointerShadowColor | Gauge pointer shadow color | string | (datum, index, data) => string | - | |
| pointerShadowBlur | Gauge pointer shadow blur factor | number | (datum, index, data) => number | - | |
| pointerShadowOffsetX | Gauge pointer shadow horizontal offset | number | (datum, index, data) => number | - | |
| pointerShadowOffsetY | Gauge pointer shadow vertical offset | number | (datum, index, data) => number | - | |
| pointerCursor | Gauge pointer mouse cursor style | string | (datum, index, data) => string | default |
text
Configure gauge indicator text styles through the text prefix.
| Property | Description | Type | Default | Required |
|---|---|---|---|---|
| textContent | Set gauge center indicator text content | string | - | |
| textX | Gauge center indicator text x-direction offset, can be set as specific value or percentage | number | string | 50% |
|
| textY | Gauge center indicator text y-direction offset, can be set as specific value or percentage | number | string | 60% |
|
| textFontSize | Gauge indicator text font size | number | (datum, index, data) => number | 20 |
|
| textFontFamily | Gauge indicator text font family | string | (datum, index, data) => string | - | |
| textFontWeight | Gauge indicator text font weight | number | (datum, index, data) => number | 800 |
|
| textTextAlign | Gauge indicator text alignment | center | end | left | right | start |
center |
|
| textTextBaseline | Gauge indicator text baseline alignment | top | middle | bottom | alphabetic | hanging |
middle |
|
| textFill | Gauge indicator text color | string | (datum, index, data) => string | #888 |
|
| textFillOpacity | Gauge indicator text opacity | number | (datum, index, data) => number | - | |
| textStroke | Gauge indicator text stroke color | string | (datum, index, data) => string | - | |
| textStrokeOpacity | Gauge indicator text stroke opacity | number | (datum, index, data) => number | - | |
| textLineHeight | Gauge indicator text line height | number | (datum, index, data) => number | - | |
| textLineWidth | Gauge indicator text stroke width | number | (datum, index, data) => number | - | |
| textLineDash | Gauge indicator text dash configuration | [number,number] | (datum, index, data) => [number , number] | - | |
| textOpacity | Gauge indicator text overall opacity | number | (datum, index, data) => number | - | |
| textShadowColor | Gauge indicator text shadow color | string | (datum, index, data) => string | - | |
| textShadowBlur | Gauge indicator text shadow blur | number | (datum, index, data) => number | - | |
| textShadowOffsetX | Gauge indicator text shadow horizontal offset | number | (datum, index, data) => number | - | |
| textShadowOffsetY | Gauge indicator text shadow vertical offset | number | (datum, index, data) => number | - | |
| textCursor | Gauge indicator text mouse cursor style | string | (datum, index, data) => string | default |
import { Chart } from '@antv/g2';
const chart = new Chart({
container: 'container',
});
chart.options({
type: 'gauge',
data: {
value: {
target: 159,
total: 400,
name: 'score',
// thresholds: [200, 400],
},
},
scale: {
color: {
range: ['l(0):0:#62CFF4 1:#2C67F2', 'l(0):0:#2C67F2 1:#00008B'],
},
y: {
range: [1, -0.5],
},
},
style: {
// Configure gauge indicator text style
textContent: (target, total) => `Ratio: ${(target / total) * 100}%`,
textFill: '#000',
textFontSize: 24,
textfontWeight: 300,
textX: '35%',
textY: '75%',
// Configure gauge pointer style
pointerStroke: '#c5c5c5',
pointershadowColor: '#333333',
pointershadowBlur: 10,
pointershadowOffsetX: 5,
pointershadowOffsetY: 5,
// Configure gauge pointer axis style
pinStroke: '#d5d5d5',
pinFill: '#d5d5d5',
pinlinewidth: 6,
pinshadowColor: '#333333',
pinshadowBlur: 30,
pinshadowOffsetX: 5,
pinshadowOffsetY: 5,
// Configure gauge arc style
arcLineWidth: 2,
arcStroke: '#fff',
arcshadowColor: '#333333',
arcshadowBlur: 30,
arcshadowOffsetX: 5,
arcshadowOffsetY: 5,
},
legend: false,
});
chart.render();
For more style configuration, you can check the style introduction page.
Try it out:
import { Chart } from '@antv/g2';
const chart = new Chart({
container: 'container',
height: 350,
});
chart.options({
type: 'gauge',
data: {
value: { target: 159, total: 400, name: 'score', thresholds: [200, 400] },
},
scale: {
color: { range: ['l(0):0:#37b38e 1:#D9C652', 'l(0):0:#D9C652 1:#f96e3e'] },
},
style: {
textContent: (target, total) => `得分:${target}
占比:${(target / total) * 100}%`,
},
legend: false,
});
chart.render();
Examples
Custom Gauge Pointer Shape
import { Chart } from '@antv/g2';
import { Path } from '@antv/g';
const chart = new Chart({ container: 'container' });
function getOrigin(points) {
if (points.length === 1) return points[0];
const [[x0, y0, z0 = 0], [x2, y2, z2 = 0]] = points;
return [(x0 + x2) / 2, (y0 + y2) / 2, (z0 + z2) / 2];
}
// 自定义指针形状
const customShape = (style) => {
return (points, value, coordinate, theme) => {
// 获取几何点中心坐标
const [x, y] = getOrigin(points);
const [cx, cy] = coordinate.getCenter();
// 计算指针方向角度
const angle = Math.atan2(y - cy, x - cx);
const length = 100; // 指针长度
const width = 8; // 指针底部宽度
// 构造指针三角形路径
return new Path({
style: {
d: [
['M', cx + Math.cos(angle) * length, cy + Math.sin(angle) * length], // 顶点
[
'L',
cx + Math.cos(angle + Math.PI / 2) * width,
cy + Math.sin(angle + Math.PI / 2) * width,
], // 底部左点
[
'L',
cx + Math.cos(angle - Math.PI / 2) * width,
cy + Math.sin(angle - Math.PI / 2) * width,
], // 底部右点
['Z'], // 闭合路径
],
fill: '#30BF78', // 填充色
},
});
};
};
chart.options({
type: 'gauge',
data: {
value: {
target: 159,
total: 424,
name: 'score',
},
},
style: {
pointerShape: customShape,
pinShape: false,
textContent: (target, total) => {
return `得分:${target}\n占比:${(target / total) * 100}%`;
},
},
});
chart.render();