guide-legend

Customise the legend (swatch) for an aesthetic.

The returned spec carries customisation only; it is bound to an aesthetic when passed through guides as colour: guide-legend(...) or similar, and applied by the legend renderer when drawing the swatch.

Usage

guide-legend(
  title: none,
  nrow: none,
  ncolumn: none,
  reverse: false,
  position: auto,
  direction: auto,
  order: none,
  byrow: false,
  align: none,
  key-size: none,
)

Parameters

Parameter	Default	Description
title	none	Override the legend title; none keeps the default from labels or scale.
nrow	none	Number of rows when laying out levels in a grid; none for default. Applies to discrete (swatch) and continuous size (scale-size-*) legends; a continuous colourbar is a single bar and ignores it.
ncolumn	none	Number of columns when laying out levels in a grid; none for default. Applies to discrete (swatch) and continuous size (scale-size-*) legends; a continuous colourbar is a single bar and ignores it.
reverse	false	Reverse the order of levels.
position	auto	Where the legend sits. One of "top", "right", "bottom", "left", "none", a Typst alignment (e.g. top + right) for inside-panel placement, or a dict (dx:, dy:) / (x:, y:) for arbitrary offsets. auto (default) inherits the side from a guides(default: ...) entry when present, otherwise falls back to "right". Wide horizontal legends on "top" / "bottom" can overflow the panel edge.
direction	auto	Flow direction of swatch entries: "horizontal" or "vertical". auto infers from position (horizontal for top/bottom, vertical otherwise).
order	none	Integer priority among multiple guides; lower draws first. none defers to the default aesthetic order.
byrow	false	Fill the swatch grid row-major when true; column-major (default) when false.
align	none	Horizontal alignment of the legend as a Typst alignment (left, center, right), applied to both the entry labels and the legend title, or none to use the per-direction default (horizontal legends centre, vertical legends left). Overrides the legend-text theme alignment for labels and the legend-title theme alignment for the title. Pass the alignment value left, not the string "left".
key-size	none	Diameter of the swatch key glyph as a Typst length (e.g. 0.3cm); none keeps the theme legend-key value. Applies to discrete (swatch) legends; a continuous colourbar or size-ladder legend ignores it because its glyph encodes the scale.

Returns

Guide dictionary tagged kind: "guide", consumed by guides.

Examples

Reverse the level order shown in the legend.

#let d = (
  (x: 1, y: 1, g: "a"),
  (x: 2, y: 2, g: "b"),
  (x: 3, y: 3, g: "c"),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", fill: "g"),
  layers: (geom-point(size: 3pt),),
  guides: guides(fill: guide-legend(reverse: true)),
  width: 10cm,
  height: 6cm,
)

Override the legend title and lay swatches out across two columns to compress the legend horizontally.

#let d = ()
#for grp in ("a", "b", "c", "d") {
  for i in range(0, 4) { d.push((x: i, y: i, g: grp)) }
}
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", fill: "g"),
  layers: (geom-point(size: 3pt),),
  guides: guides(fill: guide-legend(title: "Group", ncolumn: 2)),
  width: 10cm,
  height: 6cm,
)

Penguin species legend rendered as a 3-column legend so it sits flat under a wide panel.

#plot(
  data: penguins,
  mapping: aes(x: "flipper-len", y: "body-mass", fill: "species"),
  layers: (geom-point(size: 2pt),),
  guides: guides(fill: guide-legend(title: "Species", ncolumn: 3)),
  labels: labels(x: "Flipper Length (mm)", y: "Body Mass (g)"),
  width: 14cm,
  height: 6cm,
)

Right-align the entry labels so their right edges line up, regardless of label width.

#let d = (
  (x: 1, y: 1, g: "a"),
  (x: 2, y: 2, g: "bbbb"),
  (x: 3, y: 3, g: "cc"),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", fill: "g"),
  layers: (geom-point(size: 3pt),),
  guides: guides(fill: guide-legend(align: right)),
  width: 10cm,
  height: 6cm,
)

Centre a horizontal colourbar under its title: place the legend below the panel and set align: center so the bar and the title share one horizontal centre.

#plot(
  data: mpg,
  mapping: aes(x: "displ", y: "hwy", fill: "cty"),
  layers: (geom-point(size: 3pt),),
  labels: labels(fill: "City fuel economy (mpg)"),
  guides: guides(fill: guide-legend(position: "bottom", align: center)),
  width: 12cm,
  height: 7cm,
)

Enlarge the swatch key glyphs with key-size; the row spacing and label offset grow with the glyph so nothing overlaps.

#let d = (
  (x: 1, y: 1, g: "a"),
  (x: 2, y: 2, g: "b"),
  (x: 3, y: 3, g: "c"),
)
#plot(
  data: d,
  mapping: aes(x: "x", y: "y", fill: "g"),
  layers: (geom-point(size: 3pt),),
  guides: guides(fill: guide-legend(key-size: 0.45cm)),
  width: 10cm,
  height: 6cm,
)

See also

guides, plot.