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: "right",
  direction: auto,
  order: none,
  byrow: false,
)

Parameters

Parameter Default Description
title none Override the legend title; none keeps the default from labs or scale.
nrow none Number of rows when laying out levels in a grid; none for default.
ncolumn none Number of columns when laying out levels in a grid; none for default.
reverse false Reverse the order of levels.
position "right" 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. 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.

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,
)

Scatter chart of three coloured points with the fill legend listing levels c, b, a from top to bottom instead of the default a, b, c.

Scatter chart of three coloured points with the fill legend listing levels c, b, a from top to bottom instead of the default a, b, c.

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,
)

Scatter chart of four-level fill mapping with a custom Group legend title and the four swatches laid out in two columns.

Scatter chart of four-level fill mapping with a custom Group legend title and the four swatches laid out in two columns.

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)),
  labs: labs(x: "Flipper Length (mm)", y: "Body Mass (g)"),
  width: 14cm,
  height: 6cm,
)

Scatter chart of penguin flipper length versus body mass with a wide Species legend laid out in three columns under the panel.

Scatter chart of penguin flipper length versus body mass with a wide Species legend laid out in three columns under the panel.

See also

guides, guide-none, plot.

Back to top