theme

Build a custom theme from per-element overrides.

Pass named arguments like axis-title: element-text(size: 12pt) or panel-grid: element-blank(). Each surface is stored as an element record; the renderer reads them via resolve-element with cascade surface → parent → defaults.

The table below is the full catalogue of accepted keys. Each row lists the key, its accepted type, the default applied when unset, and the parent it inherits from (root rows are at the top of an inheritance chain). Children with inherits for the default fall back through the parent chain until a default is found. Rows are grouped by family.

Key	Type	Default	Parent
`text`	`element-text`	`element-text(size: 9pt, weight: "regular")`	(root)
`line`	`element-line`	`element-line(thickness: 0.5pt)`	(root)
`rect`	`element-rect`	`element-rect()`	(root)
`plot-title`	`element-text` or `element-typst`	`element-text(size: 12pt, weight: "bold")`	`text`
`plot-subtitle`	`element-text` or `element-typst`	`element-text(size: 9pt)`	`text`
`plot-caption`	`element-text` or `element-typst`	`element-text(size: 8pt)`	`text`
`plot-background`	`element-rect` or `element-blank`	`element-rect()`	`rect`
`plot-margin`	`margin` record	`margin()`	(root)
`axis-title`	`element-text` or `element-typst`	`element-text(size: 9pt)`	`text`
`axis-title-x`	`element-text` or `element-typst`	inherits	`axis-title`
`axis-title-x-bottom`	`element-text` or `element-typst`	inherits	`axis-title-x`
`axis-title-x-top`	`element-text` or `element-typst`	inherits	`axis-title-x`
`axis-title-y`	`element-text` or `element-typst`	inherits	`axis-title`
`axis-title-y-left`	`element-text` or `element-typst`	inherits	`axis-title-y`
`axis-title-y-right`	`element-text` or `element-typst`	inherits	`axis-title-y`
`axis-text`	`element-text` or `element-typst`	`element-text(size: 8pt)`	`text`
`axis-text-x`	`element-text` or `element-typst`	inherits	`axis-text`
`axis-text-x-bottom`	`element-text` or `element-typst`	inherits	`axis-text-x`
`axis-text-x-top`	`element-text` or `element-typst`	inherits	`axis-text-x`
`axis-text-y`	`element-text` or `element-typst`	inherits	`axis-text`
`axis-text-y-left`	`element-text` or `element-typst`	inherits	`axis-text-y`
`axis-text-y-right`	`element-text` or `element-typst`	inherits	`axis-text-y`
`axis-line`	`element-line` or `element-blank`	`element-line(thickness: 0.5pt)`	`line`
`axis-line-x`	`element-line` or `element-blank`	inherits	`axis-line`
`axis-line-x-bottom`	`element-line` or `element-blank`	inherits	`axis-line-x`
`axis-line-x-top`	`element-line` or `element-blank`	inherits	`axis-line-x`
`axis-line-y`	`element-line` or `element-blank`	inherits	`axis-line`
`axis-line-y-left`	`element-line` or `element-blank`	inherits	`axis-line-y`
`axis-line-y-right`	`element-line` or `element-blank`	inherits	`axis-line-y`
`axis-ticks`	`element-line` or `element-blank`	`element-line(thickness: 0.5pt)`	`line`
`axis-ticks-x`	`element-line` or `element-blank`	inherits	`axis-ticks`
`axis-ticks-x-bottom`	`element-line` or `element-blank`	inherits	`axis-ticks-x`
`axis-ticks-x-top`	`element-line` or `element-blank`	inherits	`axis-ticks-x`
`axis-ticks-y`	`element-line` or `element-blank`	inherits	`axis-ticks`
`axis-ticks-y-left`	`element-line` or `element-blank`	inherits	`axis-ticks-y`
`axis-ticks-y-right`	`element-line` or `element-blank`	inherits	`axis-ticks-y`
`tick-labels`	boolean	`true`	(root)
`tick-length`	length	`0.1cm`	(root)
`tick-length-x`	length	inherits	`tick-length`
`tick-length-x-bottom`	length	inherits	`tick-length-x`
`tick-length-x-top`	length	inherits	`tick-length-x`
`tick-length-y`	length	inherits	`tick-length`
`tick-length-y-left`	length	inherits	`tick-length-y`
`tick-length-y-right`	length	inherits	`tick-length-y`
`panel-grid`	`element-line` or `element-blank`	`element-line(thickness: 0.5pt)`	`line`
`panel-background`	`element-rect` or `element-blank`	`element-rect()`	`rect`
`legend-title`	`element-text` or `element-typst`	`element-text(size: 8pt)`	`text`
`legend-text`	`element-text` or `element-typst`	`element-text(size: 8pt)`	`text`
`strip-text`	`element-text` or `element-typst`	`element-text(size: 8pt)`	`text`
`strip-background`	`element-rect` or `element-blank`	`element-rect()`	`rect`
`ink`	colour	`black`	(root)
`paper`	colour	`white`	(root)
`accent`	colour	`rgb("#3366FF")`	(root)

Usage

theme(
  ..fields,
)

Parameters

Parameter	Default	Description
`..fields`		Named per-element overrides; see the description above for the full catalogue of structured and flat keys.

Returns

Theme dictionary consumed by plot.

Examples

Custom panel and grid colours via structured element records.

#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(
    text: element-text(colour: rgb("#2c3e50")),
    panel-background: element-rect(fill: rgb("#f7f0e7")),
    panel-grid: element-line(colour: rgb("#d9cfbf")),
  ),
  width: 10cm,
  height: 6cm,
)

Hide elements entirely with element-blank, useful for very minimalist figures.

#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(
    panel-grid: element-blank(),
    axis-line: element-blank(),
  ),
  width: 10cm,
  height: 6cm,
)

Tweak the scalar fields: bigger ticks, no tick labels, and a wider left margin so a long axis title fits.

#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),),
  labs: labs(y: "Cumulative Response (Per Protocol)"),
  theme: theme(
    tick-length: 0.25cm,
    tick-labels: false,
    plot-margin: margin(left: 2cm),
  ),
  width: 10cm,
  height: 6cm,
)

Usage

Parameters

Returns

Examples

See also