Gauge Chart

A gauge chart displays a single value against a defined range. It is well suited for KPIs, completion percentages, speedometers, and any scenario where the position of one value within a min/max bracket needs to be communicated at a glance. The gauge chart type is built on the same engine as radialBar but exposes additional configuration for partial arcs, threshold bands, tick marks, and needle indicators.

Gauge chart vs radialBar

ApexCharts has two related chart types for single-value indicators: gauge and radialBar. They share the same rendering engine but have different defaults and configuration surface.

	Gauge (chart.type: 'gauge')	RadialBar (chart.type: 'radialBar')
Primary use	Single KPI with a defined min/max range	Progress percentage or multi-ring comparison
Default input	Numeric value within a min/max range	Percentage (0-100)
Needle support	Yes (via plotOptions.radialBar.shape: 'needle')	No
Threshold bands	Yes	No
Multiple series	Not typical	Yes, each series is one ring

Use gauge for speedometer-style KPIs with a min/max range, threshold bands, and optional needle. Use radialBar for progress rings and multi-series radial comparisons.

Chart Configuration

Set the chart type to gauge and pass a single value in series.

chart: {
  type: 'gauge',
  height: 350,
},
series: [72],
labels: ['Progress'],

Data Format

Gauge charts accept a single numeric value in the series array. The value is interpreted against plotOptions.radialBar.min and plotOptions.radialBar.max (default 0 and 100), and a value outside that range is drawn at the nearest bound. A negative min lets the gauge show readings below zero.

On the default 0 to 100 domain the value label ends in %. On a custom domain (for example min: 0, max: 240) it shows the plain number, so add a unit with dataLabels.value.formatter.

The corresponding entry in labels is the metric name. A gauge hides it by default; set plotOptions.radialBar.dataLabels.name.show: true to display it with the value.

Basic Gauge

The default gauge uses a circular arc with the value rendered in the centre.

Semi-Circle Gauge

Constrain the arc to a half-circle with startAngle and endAngle. The chart auto-centres within the available canvas.

plotOptions: {
  radialBar: {
    startAngle: -90,
    endAngle: 90,
  },
},

Threshold Bands

Use bands to colour-code value ranges along the arc, useful for indicating safe / warning / critical zones.

plotOptions: {
  radialBar: {
    bands: [
      { from: 0,  to: 30,  color: '#FF4560' },
      { from: 30, to: 70,  color: '#FEB019' },
      { from: 70, to: 100, color: '#00E396' },
    ],
  },
},

To separate adjacent bands, set bandsStyle.gap. A number is pixels along the arc. Since 8.5.0, '1.5deg' (an angle) and '1%' (a share of the scale) look the same at every gauge size.

Tick Marks

Render major and minor ticks along the arc to make the scale readable.

plotOptions: {
  radialBar: {
    ticks: {
      show: true,
      major: { count: 11, length: 12 },
      minor: { count: 4,  length: 6  },
    },
  },
},

Needle Indicator

Switch the gauge to a needle by setting shape: 'needle'. The needle tweens between values on updateSeries calls, which makes it suitable for realtime / dashboard scenarios. It moves at the value arc's speed (chart.animations.dynamicAnimation.speed on updates); set needle.animation.duration to give it its own speed, or needle.animation.enabled: false to make it land at once.

plotOptions: {
  radialBar: {
    shape: 'needle',
    startAngle: -135,
    endAngle: 135,
    needle: {
      showValueArc: true,
      offsetY: 0,
    },
    hollow: {
      stroke: '#e0e0e0',
      strokeWidth: 1,
    },
  },
},

For a live-updating needle, see Live Needle Gauge.

Target Marks

Since 8.5.0, targets mark a value on the dial: a goal, a limit, last period's reading. They work on both gauge shapes and on every ring of a radialBar, and move with the chart on updates. value: 'series' follows the reading itself, as a pointer on the rim.

Targets are a free add-on outside the default bundle: import apexcharts/features/radial-targets, or add dist/features/radial-targets.js after the ApexCharts script. The full bundle includes it.

import 'apexcharts/features/radial-targets'

plotOptions: {
  radialBar: {
    startAngle: -135,
    endAngle: 135,
    targets: [
      { value: 80, label: { text: 'Limit' }, color: '#DC2626' },
      { value: 'series', shape: 'triangle' },
    ],
  },
},

Every target option is in the radialBar reference.

Custom Value Label

Format the value label and add custom prose with dataLabels.name.formatter and dataLabels.value.

Related

• RadialBar / Circular Gauge: multi-value radial charts and the underlying engine.
• See plotOptions.radialBar for the full set of gauge configuration options.