Skip to main content
Data labels print each observation’s value on the observation itself. Unlike the other topics in this section they are not a config field. They are a per-layer option on a geom, because a label belongs to one observation.

​
Options

​
boolean
default:"false"
Turns labels on for this layer. geom.tile() is the exception: a heatmap is read cell by cell, so its labels start on and you turn them off instead.
​
'absolute' | 'percentage'
default:"absolute"
Show the raw value, or its share of the total.
​
'auto' | 'inside' | 'outside'
default:"auto"
Where the label sits relative to the observation. 'auto' lets the engine fit, flip, rotate or drop labels as space allows; only 'auto' does any of that. 'inside' and 'outside' render exactly as asked and are never dropped. On stacked and filled cartesian bar segments 'outside' becomes 'inside', since every segment edge borders a neighbor. Pie wedges keep 'outside'.
​
'start' | 'center' | 'end' | 'panel-start' | 'panel-end'
default:"end ('center' for stacked/filled bars)"
Anchor along the observation’s value axis. 'end' is the value tip whatever the orientation or sign. 'panel-start' and 'panel-end' anchor to the panel instead of the observation’s box, so labels sit flush at the chart edge however long the geom is. Read only when position is explicit.
​
'start' | 'center' | 'end'
default:"center"
Anchor across the observation’s other axis: the bandwidth for bars, the angle for wedges, x for points, lines and areas. Read only when position is explicit.
​
number
Gap in pixels between the observation’s edge and the label. Defaults to 4 for bars, wedges and points, 8 for lines and areas. Stack totals ignore it and sit 6px off the stack end.
​
boolean
default:"false"
On stacked bars, print the stack total at the end of each stack.
​
boolean
default:"false"
On polar bars (pie and donut) prepends the category to the value (“North · 35%”). On cartesian bars draws a second label per bar with the category name, placed by the category* fields below and independent of showDataLabels. Other geoms ignore it.

​
Category labels

On cartesian bars the category label has placement fields of its own, so it can sit at the base of the bar while the value label sits at the tip:
​
'inside' | 'outside'
default:"inside"
Where the category label sits relative to its bar. There is no 'auto': category labels render exactly as asked. On stacked and filled segments 'outside' becomes 'inside'.
​
'start' | 'center' | 'end' | 'panel-start' | 'panel-end'
default:"start"
Anchor along the bar’s value axis. Takes panel anchors like justify.
​
'start' | 'center' | 'end'
default:"center"
Anchor across the bar’s bandwidth.
​
number
default:"4"
Gap in pixels between the anchored edge and the category label box.

​
Styling

This page places labels; the stylesheet paints them. Type, box padding, background, border and corner radius come from the dataLabel target and its roles: .observation and .category, each with an .inside and .outside variant, plus .aggregate for stack totals:
A label’s final position picks the variant. Over the geom it takes inside styling (white text, no background). Off the geom, by placement, by offset, or because it did not fit, it takes outside styling. Area labels always use outside styling, because a translucent fill cannot back white text. See Styling.

​
Examples

Percentage labels on a pie’s wedges, with the category name:
Totals at the top of each stacked column:

​
Related