Headline numbers

Headline numbers show a summary metric (a total, an average or the latest value) beside the chart, with an optional trend indicator. They are set through the headline section.

config({
  headline: { show: 'total', compareWith: 'previous' },
});

On a cartesian graph the headline is a strip with one card per color group (a single card when nothing is mapped to color), and it takes the place of the pill legend. The y variable must be numeric, and 'total' on position: 'fill' bars draws nothing, since every stack sums to 100%. On a pie or donut the headline is one grand total. Only show: 'total' draws anything there, and only on a position: 'fill' layer, which is how a pie is built.

Options

'total' | 'average' | 'current' | 'conversion' | 'none'

default:"none"

Which aggregate to display:

'total' — the sum of the group’s values.
'average' — the arithmetic mean.
'current' — the last value (useful for time series).
'conversion' — accepted by the type but produces no headline.
'none' — no headline.

'previous' | 'first' | 'none'

default:"none"

Reference point for the trend indicator. The trend appears only with show: 'current' on a datetime x axis, and shows the change from the reference to the latest value:

'previous' — the preceding observation.
'first' — the first observation in the group.
'none' — the default; a current headline still trends, against the first observation.

'auto' | 'small' | 'medium' | 'large'

default:"auto"

Visual size. 'auto' picks the largest of the three whose strip fits the container width.

'above' | 'center'

default:"above"

Where the headline sits. 'above' places it in the header region. 'center' places it in the hole of a donut. A pie without an inner radius has no hole, and a cartesian graph has no center, so there 'center' behaves as 'above'.

In a donut’s center

Pair position: 'center' with a donut to put the total in the hole:

pipe(
  createSpec({ x: '', y: 'revenue', color: 'region' }),
  geom.bar({ position: 'fill' }),
  coord.polar({ theta: 'y', innerRadius: 0.6 }),
  scale.x(),
  scale.y(),
  scale.color.discrete(),
  config({ headline: { show: 'total', position: 'center' } })
);

Pie & donut — the donut’s hole, home of a centerd headline
Number format — how the headline value is formatted
Styling — style.headline and style.headlineItem paint the strip and its cards

Get Started

Core concepts

Chart types

Themes

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

Options

In a donut’s center

​Options

​In a donut’s center

​Related

Options

In a donut’s center

Related