Vue ChartsRadial Gauge

Version 14.2.0

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 Copy Link

To create a Radial Gauge, use the createGauge API with the type radial-gauge.

template: `<ag-gauge :options="options"/>`,
components: {
    'ag-gauge': AgGauge,
},
data() {
    return {
        options: {
            type: 'radial-gauge',
            value: 80,
            scale: {
                min: 0,
                max: 100,
            },
        },
    };
}

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 Copy Link

Needle / Bar Copy Link

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 Copy Link

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 Copy Link

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 Copy Link

{
    cornerRadius: 99,
    cornerMode: 'container',
}

In this configuration:

  • cornerRadius specifies the amount of curvature applied to each corner.
  • cornerMode can be set to container to apply rounded corners only to the start and end of the gauge, or item for all visual items within the gauge.

Start and End Angles Copy Link

The startAngle and endAngle properties can be used to customise the start and end position of the gauge.

{
    startAngle: -135,
    endAngle: 135,
}
  • Angles are calculated clockwise, starting from the top of the gauge.

Colour Options Copy Link

Single Colour Copy Link

Both the bar and scale can be displayed using a solid fill.

{
    scale: {
        fill: '#f5f6fa',
    },
    bar: {
        fill: '#4cd137',
    },
}

Multiple Colours Copy Link

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 to continuous for a gradient, or discrete 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 Copy Link

{
    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 and continuous modes can be used with colour stops.

Targets Copy Link

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 Copy Link

{
    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 - either inside, outside, or middle.
  • size is the size of the marker, in pixels.
  • spacing is spacing from the edge of the gauge to the marker. Ignored when placement is middle.

Radial Gauge Chart Examples Copy Link

See more Radial Gauge Chart examples in the AG Charts Gallery.

API Reference Copy Link

Properties available on the AgRadialGaugeOptions interface.

type required 'radial-gauge'
Configuration for the Radial Gauge.
value required AgNumericValue
Value of the Radial Gauge.
theme AgChartTheme | AgChartThemeName
container HTMLElement | null
The element to place the rendered chart into.
width PixelSize
The width of the chart in pixels.
height PixelSize
The height of the chart in pixels.
minHeight PixelSize default: 300
Sets the minimum height of the chart. Ignored if `height` is specified.
minWidth PixelSize default: 300
Sets the minimum width of the chart. Ignored if `width` is specified.
padding Padding
Configuration for the padding of the chart. A number applies uniform padding; an object sets each side.
background AgChartBackground
Configuration for the background shown behind the chart.
title AgChartCaptionOptions
Configuration for the title shown at the top of the chart.
subtitle AgChartSubtitleOptions
Configuration for the subtitle shown beneath the chart title.
footnote AgChartFooterOptions
Configuration for the footnote shown at the bottom of the chart.
tooltip AgChartTooltipOptions
Global configuration that applies to all tooltips in the chart.
animation AgAnimationOptions
Configuration for chart animations.
contextMenu AgContextMenuOptions
Configuration for the context menu.
context ContextDefault
Context object to use in callbacks.
locale AgLocaleOptions
Configuration for localisation.
listeners AgBaseChartListeners
A map of event names to event listeners.
targets AgRadialGaugeTarget[]
Configuration for the targets.
outerRadius PixelSize
Outer radius of the gauge.
innerRadius PixelSize
Inner radius of the gauge.
outerRadiusRatio Ratio
Ratio of the outer radius of the gauge.
innerRadiusRatio Ratio
Ratio of the inner radius of the gauge.
startAngle Degree
Angle in degrees of the start of the gauge.
endAngle Degree
Angle in degrees of the end of the gauge.
segmentation AgGaugeSegmentation
Configuration for a segmented appearance.
cornerRadius number
Apply rounded corners to the gauge.
cornerMode AgGaugeCornerMode default: container
Configuration on whether to apply `cornerRadius` only to the ends of the gauge, or each individual item within the gauge.
needle AgRadialGaugeNeedleStyle
Configuration for the needle.
scale AgRadialGaugeScale
Configuration for the scale.
bar AgRadialGaugeBarStyle
Configuration for the bar.
label AgRadialGaugeLabelOptions
Configuration for the labels shown inside the shape.
secondaryLabel AgRadialGaugeSecondaryLabelOptions
Configuration for the labels shown inside the shape.
spacing PixelSize
Distance between the shape edges and the text.
cursor string
The cursor to use for the gauge. This config is identical to the CSS `cursor` property.
highlight AgHighlightOptions
Configuration for highlighting when a series or legend item is hovered over.
selection AgSelectionOptions
Configuration for data selection.
nodeClickRange InteractionRange
Range from a node that a click triggers the listener.