Skip to main content

Circular Bar

Basic Configuration​

The Circular Bar chart lays its data records evenly around a circle and draws one petal-shaped bar per record. Each bar grows from the inner edge outward proportionally to its value, and a faded background bar behind it shows the maximum. The minimum configuration looks like:

component.tsx
import { VisSingleContainer, VisCircularBar } from '@unovis/react'

function Component(props) {
  const data: number[] = props.data
  const value = (d: number) =>  d
  const color = (d: number, i: number) =>  ['var(--vis-color0)', 'var(--vis-color1)', 'var(--vis-color2)', 'var(--vis-color3)', 'var(--vis-color4)', 'var(--vis-color5)', '#57BAFF'][i % 7]

  return (
    <VisSingleContainer data={data}>
      <VisCircularBar value={value} maxValue={1} color={color}/>
    </VisSingleContainer>
  )
}
Loading...

Max Value​

A bar with value === maxValue reaches the outer radius of the chart. When maxValue is undefined (the default), the maximum is derived from the data. Pass a number to use one max for all bars, a per-datum accessor when each bar should scale against its own target, or an array indexed by the datum's position in data:

// Auto-derive max from data (default)
maxValue={undefined}

// Single shared max
maxValue={100}

// Per-bar target
maxValue={d => d.target}
<VisCircularBar value={value} maxValue={maxValue} color={color}/>
Loading...

Bar Shape​

The bars get their petal-like look from four properties, all in pixels. By default they are derived from the chart radius (inner radius 26%, outer corners 12%, gap 3%, and inner corners large enough to merge into a single rounded tip), so the proportions hold at any size. The corner radii are reduced automatically when a bar is too short or too narrow to fit them.

Inner Radius​

innerRadius is the radius of the hole in the middle of the chart. Bars start at the inner radius (unless barPadding and innerCornerRadius force them to start farther away from the center), and by default their inner corners merge into a single rounded tip touching it. Set it to 0 to make the tips converge towards the center.

<VisCircularBar
  value={value} 
  maxValue={1} 
  color={color} 
  innerRadius={40}
/>
Loading...

Bar Padding​

barPadding is the gap between neighbouring bars. Unlike an angular padding, the gap has the same width along the whole side of a bar, so the sides of neighbouring bars stay parallel.

<VisCircularBar
  value={value} 
  maxValue={1} 
  color={color} 
  barPadding={16}
/>
Loading...

Corner Radius​

cornerRadius rounds the two outer corners of a bar.

<VisCircularBar
  value={value} 
  maxValue={1} 
  color={color} 
  cornerRadius={40}
/>
Loading...

Inner Corner Radius​

innerCornerRadius rounds the two inner corners of a bar. By default it is large enough for the two corners to merge into a single rounded tip touching the inner radius, with a rounding of at least a fraction of the bar's width (so very narrow bars or a small inner radius start slightly beyond it). Smaller values leave a piece of the inner circle between the corners, larger values move the tip away from the center. Bars too wide for a tip, e.g. three bars over the full circle, keep two rounded corners and a short inner arc.

<VisCircularBar
  value={value} 
  maxValue={1} 
  color={color} 
  innerCornerRadius={10}
/>
Loading...

Angle Range​

By default the bars cover the full circle and the first bar is centered at the top. Pass a [start, end] tuple in radians to render a partial range or to rotate the chart. The bars are distributed evenly within it, and the first one starts at start. At 180° and more (i.e. one or two bars over the full circle) the padded sides of a bar never meet, so such bars are drawn as regular arcs instead of petals, with cornerRadius rounding all four corners (innerCornerRadius doesn't apply to them).

<VisCircularBar
  value={value} 
  maxValue={1} 
  color={color} 
  angleRange={[-1.5707963267948966,1.5707963267948966]}
/>
Loading...

Minimum Bar Length​

Bars representing very small values can become too small to notice. barMinLength sets the minimum length of a bar in pixels, measured from its inner edge to its outer edge, so that such bars remain visible. It defaults to 0.

0 counts as a value, so zero bars are extended to the minimum length too. Missing data is different: when the value accessor returns null or undefined, the bar is not rendered at all and only its background remains. In the example below the bars are, clockwise from the top: a regular value, a tiny value, 0, null and another regular value:

<VisCircularBar
  value={value} 
  maxValue={1} 
  color={color} 
  barMinLength={20}
/>
Loading...

Sorting​

Provide a sortFunction to control the bar order independently of how the data was provided:

<VisCircularBar
  value={value} 
  maxValue={1} 
  color={color} 
  sortFunction={sortFunction}
/>
Loading...

Radius​

radius sets the outer radius of the chart in pixels. When undefined, the chart fills the available space.

<VisCircularBar value={value} maxValue={1} color={color} radius={100}/>
Loading...

Custom Color​

Customize the colors with a color accessor:

component.tsx
function Component(props) {
  const data: number[] = props.data
  const value = (d: number) =>  d
  const color = (d: number, i: number) =>  ['#2FB8B0', '#57B24A', '#FF6A2B', '#FF3B5C', '#A53CF0', '#7A5CFF', '#1F7CFF'][i]

  return (
    <VisCircularBar value={value} maxValue={1} color={color}/>
  )
}
Loading...

Icons​

Use icon to display a small icon at the inner end of each bar. The icon is hidden when its bar is too short to fit it.

component.tsx
import { VisSingleContainer, VisCircularBar } from '@unovis/react'

function Component(props) {
  const data: number[] = props.data
  const svgDefs = `<symbol id="heart" viewBox="0 0 24 24">...</symbol> ...`
  const value = (d: number) =>  d
  const color = (d: number, i: number) =>  ['var(--vis-color0)', 'var(--vis-color1)', 'var(--vis-color2)', 'var(--vis-color3)', 'var(--vis-color4)', 'var(--vis-color5)', '#57BAFF'][i % 7]
  const icon = (d: number, i: number) =>  ['#heart', '#sun', '#drop', '#bolt', '#moon', '#star', '#leaf'][i]

  return (
    <VisSingleContainer
      svgDefs={svgDefs} 
      data={data}
    >
      <VisCircularBar
        value={value} 
        maxValue={1} 
        color={color} 
        icon={icon} 
        iconSize={18}
      />
    </VisSingleContainer>
  )
}
Loading...

icon accepts either a href to an SVG symbol defined in the container's svgDefs, like in the example above, or text: an icon font glyph (e.g. '&#xf004;' for Font Awesome's heart, with the font set via the --vis-circular-bar-icon-font-family and --vis-circular-bar-icon-font-weight CSS variables) or a Unicode symbol. SVG icons are filled with the --vis-circular-bar-icon-color CSS variable, which is also available as currentColor for strokes. Icons don't capture pointer events, so hovering them triggers the events of the bar underneath (e.g. its tooltip).

Icon Size​

iconSize sets the size of the icons in pixels. When undefined, it's 8% of the chart radius.

<VisCircularBar
  value={value} 
  maxValue={1} 
  color={color} 
  icon={icon} 
  iconSize={18}
/>
Loading...

Background​

By default each bar has a faded background of the maximum length behind it. Disable it with showBackground={false}:

<VisCircularBar
  value={value} 
  maxValue={1} 
  color={color} 
  showBackground={true}
/>
Loading...

The background color is configured via the --vis-circular-bar-background-color and --vis-dark-circular-bar-background-color CSS variables.

Events​

The following selectors are available for events:

import { CircularBar } from '@unovis/ts'
...
events = {
    [CircularBar.selectors.bar]: { },
    [CircularBar.selectors.background]: { },
}
<VisCircularBar
  value={value} 
  maxValue={1} 
  color={color} 
  events={events}
/>

CSS Variables​

All supported CSS variables and their default values
--vis-circular-bar-background-color: #E7E9F3;
--vis-circular-bar-bar-stroke-width: 0;
--vis-circular-bar-bar-stroke-color: undefined;
--vis-circular-bar-icon-color: rgba(255, 255, 255, 0.9);
--vis-circular-bar-icon-font-family: undefined;
--vis-circular-bar-icon-font-weight: normal;
--vis-dark-circular-bar-background-color: #444444;
--vis-dark-circular-bar-icon-color: rgba(255, 255, 255, 0.9);

Component Props​

NameTypeDescription
* required property