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. Offsets are read from the nudge-x and nudge-y aesthetics: a number shifts in data units, a Typst length shifts in canvas units. Setting segment: true draws a connector back to the anchor that avoids the other label boxes of the same layer.

Usage

geom-label(
  mapping: none,
  data: none,
  size: 8pt,
  colour: auto,
  font: auto,
  fill: auto,
  stroke: 0.4pt,
  alpha: auto,
  inset: 2pt,
  radius: 1pt,
  anchor: "center",
  angle: 0deg,
  segment: false,
  segment-colour: auto,
  segment-stroke: 0.4pt,
  min-segment-length: 0.05,
  arrow: false,
  arrow-length: 4pt,
  box-padding: 0.05,
  repel: false,
  point-padding: 0.05,
  max-iter: 100,
  force-pull: 0.1,
  force-push: 0.2,
  force-segment: 0.3,
  seed: 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. May map nudge-x and nudge-y for per-row offsets in data units.
data	none	Layer-specific dataset, or a function applied to the plot data returning the layer frame. 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.
font	auto	Label font family. auto uses the theme text font, then the document font.
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.
angle	0deg	Rotation applied to each label box (a Typst angle, e.g., 45deg). Positive angles rotate anticlockwise about the anchor.
segment	false	Draw a connector from each box back to its anchor point. When true, the connector is routed to avoid the AABBs of other boxes of the same layer; dropped when no L-bend clears the obstacles.
segment-colour	auto	Connector paint. auto inherits the theme ink.
segment-stroke	0.4pt	Connector thickness (a Typst length).
min-segment-length	0.05	Connectors shorter than this distance (canvas units, 1 = 1cm) are suppressed.
arrow	false	Draw a small V-mark at the anchor end of the connector.
arrow-length	4pt	Arrow stroke length (a Typst length).
box-padding	0.05	Extra cm padding added around each measured box when routing connectors.
repel	false	Repel boxes off each other (and off their anchor points) via an iterative force-based layout, ggrepel-style. Pair with segment: true to keep the visual link to each anchor.
point-padding	0.05	Minimum clearance (cm) between a box and any anchor point when repel is on.
max-iter	100	Maximum number of repulsion iterations.
force-pull	0.1	Strength of the spring pull that keeps each box near its anchor.
force-push	0.2	Strength of the repulsion between overlapping boxes.
force-segment	0.3	Strength of the penalty that pushes a box off another label’s connector path.
seed	0	Random seed for the small initial jitter applied to coincident anchors.
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(mapping: aes(nudge-y: 0.25cm)),
  ),
  scales: (scale-y-continuous(expand: 15%),),
  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-label(
      mapping: aes(nudge-y: 0.3cm),
      fill: rgb("#fff7e6"),
      colour: rgb("#cc7a00"),
      stroke: 0.6pt,
      radius: 3pt,
      inset: 4pt,
    ),
  ),
  scales: (scale-y-continuous(expand: 15%),),
  width: 10cm,
  height: 6cm,
)

See also

geom-text, aes.