element-text

Text element: font size, weight, colour, and angle.

Pass the result to theme under keys like axis-text, axis-title, legend-text, or legend-title.

Usage

element-text(
  size: none,
  weight: none,
  colour: none,
  angle: none,
  font: none,
  margin: none,
  align: none,
)

Parameters

Parameter Default Description
size none Text size. Either an absolute Typst length (e.g., 12pt), a ratio (e.g., 80%) scaling the parent surface size, or none to inherit the parent size unchanged. Absolute lengths win outright; ratios cascade proportionally, so setting the base text size resizes every surface that inherits via a ratio.
weight none Font weight (e.g., "regular", "bold"), or none to inherit.
colour none Text colour, or none to inherit.
angle none Rotation angle (a Typst angle), or none to inherit. Honoured on every text surface: axis tick labels (axis-text, seeding the guide-axis angle, which overrides it), axis titles, strip text, the legend title and entry labels, and the plot title, subtitle, and caption. Axis titles fall back to their natural angle (0deg for x, 90deg for y) when unset.
font none Font family (e.g., "sans", "serif"), or none to inherit.
margin none Per-side spacing built with margin. Each side accepts a Typst length (absolute or relative); em is preferred so spacing scales with the surface font size. Sides left at auto fall through to the renderer default. none keeps every side at the default.
align none Horizontal alignment of the text within its surface as a Typst alignment (left, center, right), or none to use the per-surface default (title and subtitle left, caption right, axis titles and strip text centred, legend title left, legend entry labels centred in horizontal legends and left in vertical legends). Independent of the surrounding container’s alignment. Axis tick labels (axis-text) are positioned by anchor and ignore this field.

Returns

Element dictionary consumed by theme.

Examples

Bigger axis-title font passed via theme.

#let d = range(0, 10).map(i => (x: i, y: i * 0.5))
#plot(
  data: d,
  mapping: aes(x: "x", y: "y"),
  layers: (geom-point(size: 2pt),),
  theme: theme(axis-title: element-text(size: 14pt)),
  width: 10cm,
  height: 6cm,
)

Scatter plot of y against x with axis titles enlarged to 14pt via element-text passed to theme.

Scatter plot of y against x with axis titles enlarged to 14pt via element-text passed to theme.

Combine multiple text fields and a rotation angle on axis tick labels.

#let d = (
  (q: "Q1", y: 3), (q: "Q2", y: 5), (q: "Q3", y: 4), (q: "Q4", y: 6),
)
#plot(
  data: d,
  mapping: aes(x: "q", y: "y"),
  layers: (geom-col(),),
  theme: theme(axis-text: element-text(
    size: 9pt,
    angle: 30deg,
    colour: rgb("#1f77b4"),
  )),
  width: 10cm,
  height: 6cm,
)

Bar chart of y across quarterly categories with axis tick labels rendered in blue 9pt text rotated 30 degrees.

Bar chart of y across quarterly categories with axis tick labels rendered in blue 9pt text rotated 30 degrees.

Widen the gap between the axis tick labels and the axis title using a relative margin that tracks the title font size.

#let d = range(0, 10).map(i => (x: i, y: i * 0.5))
#plot(
  data: d,
  mapping: aes(x: "x", y: "y"),
  layers: (geom-point(size: 2pt),),
  theme: theme(axis-title: element-text(
    size: 11pt,
    margin: margin(top: 1.6em, right: 1.6em),
  )),
  width: 10cm,
  height: 6cm,
)

Scatter plot of y against x with extra 1.6em padding above and to the right of the axis titles so they sit further from the ticks.

Scatter plot of y against x with extra 1.6em padding above and to the right of the axis titles so they sit further from the ticks.

Relative versus absolute sizes: a 12pt base text rescales every inheriting surface, a 120% ratio on the axis titles scales them relative to that base, and an absolute 18pt pins the plot title outright.

#let d = range(0, 10).map(i => (x: i, y: i * 0.5))
#plot(
  data: d,
  mapping: aes(x: "x", y: "y"),
  layers: (geom-point(size: 2pt),),
  labels: labels(title: "Relative and absolute", x: "X", y: "Y"),
  theme: theme(
    text: element-text(size: 12pt),
    axis-title: element-text(size: 120%),
    plot-title: element-text(size: 18pt, weight: "bold"),
  ),
  width: 10cm,
  height: 6cm,
)

Scatter plot of y against x with a 12pt base text size, axis titles scaled to 120 percent of it, and the plot title pinned to an absolute 18pt.

Scatter plot of y against x with a 12pt base text size, axis titles scaled to 120 percent of it, and the plot title pinned to an absolute 18pt.

See also

theme, element-line, element-rect, element-blank, element-typst, margin.

Back to top