geom-label

Boxed text label layer reading strings from the label aesthetic.

One boxed text block is drawn per row at the mapped (x, y). The box takes its own fill, stroke, inset, and corner radius.

Usage

geom-label(
  mapping: none,
  data: none,
  size: 8pt,
  colour: auto,
  fill: auto,
  stroke: 0.4pt,
  alpha: auto,
  inset: 2pt,
  radius: 1pt,
  anchor: "center",
  dx: 0,
  dy: 0,
  stat: "identity",
  position: "identity",
  inherit-aes: true,
)

Parameters

Parameter	Default	Description
mapping	none	Layer-specific aesthetic mapping built with aes. Must map x, y, and label.
data	none	Layer-specific dataset. Falls back to the plot data when none.
size	8pt	Text size (a Typst length).
colour	auto	Paint applied to both the box outline and the label text. auto resolves via the colour scale, falling back to the theme ink only when neither colour nor fill is set.
fill	auto	Box fill colour. auto resolves via the fill scale, falling back to the theme paper only when neither colour nor fill is set.
stroke	0.4pt	Box outline thickness (a Typst length) or stroke dictionary; none disables the outline.
alpha	auto	Box and text opacity in [0, 1]. auto honours any mapped alpha aesthetic.
inset	2pt	Padding between text and box border (a Typst length).
radius	1pt	Corner radius of the box (a Typst length).
anchor	"center"	CeTZ anchor (e.g., "center", "west") controlling placement.
dx	0	Horizontal offset, as a number (canvas units, 1 = 1cm) or a Typst length (e.g., 4pt, 2mm).
dy	0	Vertical offset, as a number (canvas units, 1 = 1cm) or a Typst length (e.g., 4pt, 2mm).
stat	"identity"	Statistical transform name. Usually "identity".
position	"identity"	Position adjustment name. Usually "identity"; pass "nudge" to shift labels off their points.
inherit-aes	true	Whether to merge the plot-level mapping into this layer’s mapping.

Returns

Layer dictionary consumed by plot.

Examples

Default boxed labels nudged above their points.

#let d = (
  (x: 1, y: 2, name: "a"),
  (x: 2, y: 4, name: "b"),
  (x: 3, y: 3, name: "c"),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", label: "name"),
  layers: (
    geom-point(size: 2pt),
    geom-label(dy: 0.25),
  ),
  width: 10cm,
  height: 6cm,
)

Customise fill, stroke, and radius to match a coloured callout style.

#let d = (
  (x: 1, y: 2, name: "alpha"),
  (x: 2, y: 4, name: "beta"),
  (x: 3, y: 3, name: "gamma"),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", label: "name"),
  layers: (
    geom-point(size: 2pt),
    geom-label(
      fill: rgb("#fff7e6"),
      stroke: 0.6pt + rgb("#cc7a00"),
      radius: 3pt,
      inset: 4pt,
      dy: 0.3,
    ),
  ),
  width: 10cm,
  height: 6cm,
)

See also

geom-text, aes.