RadialBar / Circular Gauge

What is a Radial Bar Chart/Circular Gauge?

A Radial Bar Chart, or Circular Gauge, is a typical Bar Chart plotted on a polar coordinate system (instead of a Cartesian plane). It indicates values on a circular numeric scale in terms of percentage with longer bars indicating larger values.

With ApexCharts Radial Bar Chart, you can represent data in several formats such as: multiple Radial Bar Charts, Radial Bar with an image, and even in semi-circular Gauge forms.

What are Radial Bar Charts used for?

Radial Bar Charts or Circular Gauge are mostly used in single-unit data to indicate progress/activity. They are also very valuable when you want to visualize comparisons between categories by using circularly shaped bars.

RadialBar vs gauge

Both radialBar and gauge draw on a polar coordinate system. The key differences:

• radialBar draws one arc per series, forming concentric rings when there are multiple series. Values are read as a percentage (0 to 100) by default, and you can set plotOptions.radialBar.min and max for any other domain.
• gauge reads a raw numeric value against the same plotOptions.radialBar.min and max. It is designed for a single value with optional threshold bands and a needle indicator.

If you want to show a single value like "CPU temperature: 72°C" with warning/critical zones, use gauge. If you want to show completion percentages for several metrics as overlapping rings, use radialBar.

In ApexCharts, switching between them is one config change: chart.type: 'gauge' vs chart.type: 'radialBar'.

Does RadialBar support negative values?

Yes, when the domain includes them. A series value is placed on the plotOptions.radialBar.min to max domain, and anything outside it is drawn at the nearest bound. With the default min: 0, a negative value is drawn at zero and renders as an empty ring with no error and no console warning. This is why a negative value looks like a bug: nothing tells you it fell outside the domain.

Set a negative min and the arc shows the reading. The value label keeps the sign, and on a custom domain the default label drops the %, so add the unit yourself:

const options = {
  chart: { type: 'radialBar', height: 320 },
  series: [-12],
  plotOptions: {
    radialBar: {
      min: -30,
      max: 50,
      dataLabels: {
        value: { formatter: (val) => `${val}°C` },
      },
    },
  },
  labels: ['Freezer'],
}

const chart = new ApexCharts(document.querySelector('#chart'), options)
chart.render()

The tradeoff is real and worth naming: the arc is measured from min, not from zero, so here -12 fills 22.5% of the ring (18 of the 80 units between -30 and 50). The ring is no longer proportional to the value a reader has in mind. Use it when the ring is decorative and the number carries the meaning.

A needle gauge reads the same domain, and suits a signed value better because the needle points at a position rather than filling an amount. With needle.showValueArc: true, the arc ends where the needle points:

const options = {
  chart: { type: 'gauge', height: 320 },
  series: [-12],
  plotOptions: {
    radialBar: {
      shape: 'needle',
      min: -30,
      max: 50,
      startAngle: -120,
      endAngle: 120,
      bands: [
        { from: -30, to: 0, color: '#2E93fA' },
        { from: 0, to: 50, color: '#FF4560' },
      ],
      dataLabels: {
        value: { formatter: (val) => `${val}°C` },
      },
    },
  },
  labels: ['Freezer'],
}

const chart = new ApexCharts(document.querySelector('#chart'), options)
chart.render()

Which option fits which case

What you have	Use
A single signed value, for example a temperature that can fall below zero	chart.type: 'gauge' with shape: 'needle' and a negative min
Signed values where the sign itself is the point, and you want them compared	A bar or column chart, which plots negatives natively
Percentages or progress that cannot go below zero	radialBar, which is what it is designed for
A signed range you specifically want as a filled ring	radialBar or gauge with a negative min, as above

Pie and donut charts read a negative value as zero, since a negative slice has no meaningful angle in a part-of-whole chart.

Behaviour verified against ApexCharts 8.2.0.

How do you make a Radial Bar?

In this section, we will show you how to make a Radial Bar Chart, how to set custom colors, how to change the startAngle and endAngle, and will demonstrate how you can easily display data labels.

By default, radialBar/gauge values are interpreted as percentages (0 to 100). To plot arbitrary domains, set plotOptions.radialBar.min and max to your value range (e.g. series: [120] with min: 0, max: 240). The default value label appends % only on the 0 to 100 domain, so on a custom domain it shows the plain number; override dataLabels.value.formatter to add a unit.

Basic Circle Chart

We will start with a very simple RadialBar / Circle Chart and gradually change some options.

The above example shows a basic circle chart with no additional customizations. Next, we will do some customizations in track / hollow background and colors

• Change the stroke's lineCap
• Change the inner hollow size
• Customize the fontsize and color of the dataLabels

Next, we make a couple more changes to make it more visually appealing.

Customizing Colors

We will do the following changes to customize track/hollow background color

• Add a background color to hollow
• Add a subtle dropShadow to track
• Fill path with gradient color

Next, we convert this Circle Chart into a Radial Gauge by changing 2 properties - startAngle & endAngle

Custom Angle

• Change startAngle and endAngle of plotOptions.radialBar
• Change startAngle and endAngle of plotOptions.radialBar.track
• Change the hollow background colors of track color

Target marks

Since 8.5.0, plotOptions.radialBar.targets draws a mark at a value on any ring, such as each metric's goal. Pick the ring with seriesIndex. It needs the apexcharts/features/radial-targets add-on, which the full bundle includes.

DataLabels

The below code shows how to display data-labels in the inner circle of chart for each series when user hovers over each bar.
There is also an optional total property which, by default, shows the average of all values of the series array (their sum divided by the number of series). You can apply a custom formatter to the plotOptions.radialBar.dataLabels.total.formatter function to modify the output.

plotOptions: { radialBar: { dataLabels: { name: { show: true, }, value: { show: true, fontSize: '14px', formatter: function (val) { return val + '%' } }, total: { show: true, label: 'Total' } } } }

To view all options for dataLabels, please view the radialBar configuration