geom-text

Text label layer reading strings from the label aesthetic.

One text block is drawn per row at the mapped (x, y). Offsets are mapped via 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 point, routed to avoid the other labels of the same layer.

Usage

geom-text(
  mapping: none,
  data: none,
  size: 8pt,
  colour: auto,
  font: auto,
  alpha: auto,
  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	Fixed text colour. auto inherits the theme ink. Used when no colour mapping is active.
font	auto	Label font family. auto uses the theme text font, then the document font.
alpha	auto	Text opacity in [0, 1]. auto honours any mapped alpha aesthetic.
anchor	"center"	CeTZ anchor (e.g., "center", "west") controlling placement.
angle	0deg	Rotation applied to each label (a Typst angle, e.g., 45deg). Positive angles rotate anticlockwise about the anchor.
segment	false	Draw a connector from each label back to its anchor point. When true, the connector is routed to avoid the AABBs of other labels of the same layer; the connector is 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 to avoid tiny stubs.
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 label box when routing connectors and clipping to the label edge.
repel	false	Repel labels 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 label 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 label near its anchor.
force-push	0.2	Strength of the repulsion between overlapping labels.
force-segment	0.3	Strength of the penalty that pushes a label off another label’s connector path.
seed	0	Random seed for the small initial jitter applied to coincident anchors. Same seed produces the same layout.
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

Labels nudged above their points via nudge-y.

#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-text(mapping: aes(nudge-y: 0.2cm)),
  ),
  scales: (scale-y-continuous(expand: 15%),),
  width: 10cm,
  height: 6cm,
)

Per-row offsets via nudge-x/nudge-y plus connectors back to each anchor.

#let d = (
  (x: 1, y: 2, name: "a", nx: 0.5, ny: 0.4),
  (x: 2, y: 4, name: "b", nx: -0.4, ny: 0.5),
  (x: 3, y: 3, name: "c", nx: 0.4, ny: -0.4),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", label: "name", nudge-x: "nx", nudge-y: "ny"),
  layers: (
    geom-point(size: 2pt),
    geom-text(segment: true),
  ),
  scales: (scale-x-continuous(expand: 40%),scale-y-continuous(expand: 40%),),
  width: 10cm,
  height: 6cm,
)

See also

geom-label, aes.