Reference

Every public function in the library, grouped by role.

Core

aes - Bind column names to visual channels to form an aesthetic mapping.
after-scale - Transform an aesthetic’s resolved value just before it reaches the geom’s draw step.
after-stat - Bind an aesthetic to a column produced by the layer’s stat, or to a per-row computation over the post-stat data.
as-factor - Coerce a column to string factors, or tag an aesthetic as discrete.
as-numeric - Coerce a column to numeric, or tag an aesthetic as continuous.
compose - Arrange multiple plots into a grid or stack with a shared, hoisted legend.
defer - Build a deferred panel for compose.
from-theme - Pull a value from the resolved theme at render time.
plot - Compose a layered plot from data, aesthetics, and geom layers.
stage - Compose all three late-binding lanes for a single aesthetic.
typst - Mark a value for Typst-markup evaluation.

Datasets

economics - US monthly economic time series (subset).
mpg - Fuel economy of 30 cars (small fuel-economy reference dataset).
penguins - Morphological measurements for 344 penguins (Palmer Archipelago).

Labels

labels - Build a label dictionary for the plot title, subtitle, caption, and axes.

Guides

draw-key-blank - Draw-key that draws nothing.
draw-key-line - Draw-key returning a short horizontal line.
draw-key-path - Draw-key returning a short polyline.
draw-key-point - Draw-key returning a small filled circle.
draw-key-rect - Draw-key returning a small filled rectangle.
guide-axis - Customise the x- or y-axis tick labels.
guide-axis-logticks - Add minor tick marks at log-scale subdivisions on a transform: "log10" axis.
guide-axis-stack - Stack multiple x or y guides on a single axis.
guide-axis-theta - Customise the theta (angular) axis under coord-radial.
guide-custom - Render arbitrary Typst content as a legend slot.
guide-legend - Customise the legend (swatch) for an aesthetic.
guides - Bind guide specifications to aesthetics.

Geoms

geom-blank - Invisible layer used to extend trained scales without drawing marks.

Areas and ribbons

geom-area - Area layer: filled polygon from y = 0 up to y along x, per group.
geom-ribbon - Filled band between ymin and ymax along the x aesthetic, per group.
geom-smooth - Fitted trend line with an optional confidence ribbon.

Bars and histograms

geom-bar - Bar layer that counts rows per x level (stat-count).
geom-col - Bar layer with heights taken from the y aesthetic.
geom-freqpoly - Frequency polygon: a line through per-bin counts of the x aesthetic.
geom-histogram - Histogram layer: bars of binned counts along the x aesthetic.

Contours

geom-contour - Contour-line layer: marching-squares iso-lines over a regular (x, y, z) grid. Pair with a continuous colour scale on _level to shade by height.
geom-contour-filled - Filled iso-band layer: marching-squares cell clipping over a regular (x, y, z) grid. Pair with a continuous fill scale on _level to shade each band by its lower bound.

Distributions

geom-boxplot - Boxplot layer: draws a Tukey box, whiskers, and outlier points per group.
geom-density - Density layer: Gaussian kernel density estimate of the x aesthetic.
geom-density-2d - 2D density layer: contour lines of the estimated (x, y) density.
geom-density-2d-filled - Filled 2D density layer: shaded bands of the estimated (x, y) density.
geom-density-ridges - Ridgeline layer: overlapping filled density curves of x per y bucket.
geom-dotplot - Dotplot layer: one dot per observation, stacked within bins.
geom-qq - Q-Q point layer: sorted sample versus theoretical quantile.
geom-qq-line - Q-Q reference line layer fitted through the IQR of the sample.
geom-quantile - Quantile-regression layer: a fitted line per requested τ.
geom-rug - Marginal rug ticks at each row’s x and / or y position.
geom-violin - Violin layer: mirrored density silhouette of y per x bucket.

Intervals and errors

geom-crossbar - Crossbar layer: a box from ymin to ymax with a horizontal bar at y.
geom-errorbar - Errorbar layer: vertical range with a horizontal cap at each end.
geom-errorbarh - Horizontal errorbar layer: range with a vertical cap at each end.
geom-linerange - Linerange layer: one vertical line from ymin to ymax at each x.
geom-pointrange - Pointrange layer: a marker at (x, y) plus a linerange from ymin to ymax.

Lines and paths

geom-curve - Curved segment layer: one quadratic bezier from (x, y) to (xend, yend) per row.
geom-function - Polyline of fun(x) sampled uniformly across the x-range.
geom-line - Line layer connecting observations in x order, one path per group.
geom-path - Path layer connecting observations in row order, one path per group.
geom-segment - Segment layer: one line from (x, y) to (xend, yend) per row.
geom-spoke - Spoke layer: one segment from (x, y) along (angle, radius) per row.
geom-step - Step layer connecting observations as a stair-step path, one per group.

Points

geom-beeswarm - Beeswarm layer: points offset sideways into a density-shaped swarm.
geom-count - Count layer drawing one marker per unique (x, y), sized by frequency.
geom-jitter - Scatter layer with position-jitter applied by default.
geom-point - Scatterplot layer drawing a marker for each row at (x, y).

Polygons and shapes

geom-ellipse - Ellipse layer: draws one closed ellipse per row from (x0, y0, a, b, angle).
geom-mark - Annotation layer enclosing each group with a chosen shape.
geom-polygon - Polygon layer: one closed filled polygon per group.

Rectangles and bins

geom-bin-2d - Two-dimensional bin layer: counts (x, y) into a rectangular grid and draws one rectangle per non-empty cell. The fill aesthetic defaults to _count, so a continuous fill scale (scale-viridis-c, etc.) shades the cells by frequency.
geom-hex - Hex bin layer: counts (x, y) into a pointy-top hex grid and draws one hexagon per non-empty cell. Default fill encodes count via the fill scale.
geom-rect - Rectangle layer drawing one filled box per row from the four corners.
geom-tile - Tile layer: filled rectangle centred at (x, y) per row.

Reference lines

geom-abline - Straight reference line described by slope and intercept.
geom-hline - Horizontal reference line at one or more y intercepts.
geom-vline - Vertical reference line at one or more x intercepts.

Text and annotations

annotate - Build a one-row annotation layer dispatching to a named geom.
geom-label - Boxed text label layer reading strings from the label aesthetic.
geom-text - Text label layer reading strings from the label aesthetic.
geom-typst - Text label layer whose label aesthetic is always evaluated as Typst markup.

Stats

Binning

stat-bin - Bin statistic: partition x into uniform-width bins, count rows per bin.
stat-bin-2d - Two-dimensional bin statistic: partition (x, y) into a rectangular grid and count rows per cell.
stat-bin-hex - Two-dimensional hexagonal bin statistic: partition (x, y) into a pointy-top hex grid and count rows per cell.
stat-bindot - Dot-density bin statistic: emit one stacked row per observation.

Distributions

stat-boxplot - Boxplot statistic: per-x five-number summary with outlier list.
stat-contour - Marching-squares contour statistic.
stat-contour-filled - Filled iso-band statistic. Partitions the (x, y, z) field into bands defined by successive levels and emits one closed polygon per cell that touches each band. Pair with geom-polygon or geom-contour-filled.
stat-density - Density statistic: Gaussian kernel density estimate of the x sample.
stat-density-2d - 2D density statistic: iso-lines of a Gaussian kernel density estimate.
stat-density-2d-filled - Filled 2D density statistic: iso-bands of a Gaussian kernel density estimate.
stat-density-ridges - Ridgeline statistic: Gaussian kernel density estimate of x per y bucket.
stat-ecdf - ECDF statistic: one row per unique x value with the cumulative fraction.
stat-ellipse - Covariance-ellipse statistic: one ellipse per group from the sample covariance of (x, y).
stat-qq - Q-Q statistic: theoretical-vs-sample pairs against a reference distribution.
stat-qq-line - Q-Q reference-line statistic: two endpoints of the IQR-fitted line.
stat-ydensity - Y-density statistic: Gaussian kernel density estimate of y per x bucket.

Distributions and summaries

stat-difference - Difference statistic: ribbon between two series, split at every crossing.
stat-waffle - Waffle statistic: turn per-group counts into unit grid cells.

Functions and helpers

stat-align - Align statistic: resample each group onto a shared x-grid.
stat-connect - Connection statistic: expand consecutive points with intermediate vertices.
stat-function - Sample fun at n points across x-limits and emit (x, y) rows.
stat-identity - Identity statistic: returns data and mapping unchanged.
stat-manual - Manual statistic: run a closure on the data array inside the layer.

Smoothing and regression

stat-quantile - Quantile regression statistic: fit one line per τ and sample it.
stat-smooth - Smoother statistic: fitted curve with a pointwise confidence band.

Summaries

stat-count - Count statistic: one output row per distinct x level with y = count.
stat-sum - Sum statistic: one output row per unique (x, y) pair with _n and _prop.
stat-summary - Per-axis reduction to a central value and an uncertainty band.
stat-summary-2d - Two-dimensional summary statistic.
stat-summary-bin - Summary statistic over uniform x bins.
stat-summary-hex - Hex-grid summary statistic.
stat-unique - Unique statistic: keep the first row per (x, y) key, drop later duplicates.

Helpers

get-alt-text - Read the alt text stored on a plot spec.
qnorm - Inverse of the standard-normal cumulative distribution function.
resolution - Smallest non-zero gap between unique numeric values in values.

Binning helpers

cut-interval - Cut a numeric vector into n equal-width bins.
cut-number - Cut a numeric vector into n bins of (approximately) equal count.
cut-width - Cut a numeric vector into bins of fixed width.

Data wrangling

anti-join - Keep the rows of x that have no match in y, adding no columns.
bind-cols - Glue datasets side by side (column bind).
bind-rows - Stack datasets on top of each other (row union).
count - Count the rows in each group, one output row per group.
distinct - Keep the first row of each distinct combination of the named columns.
drop-na - Drop rows carrying a missing value in the named columns.
full-join - Keep every row of both x and y, matching on the key columns.
inner-join - Keep only the rows of x and y that share a key.
left-join - Keep every row of x, adding the matching columns from y.
pivot-longer - Melt several columns into a single name/value column pair (wide to long).
pivot-wider - Spread a name column and a value column into one column per name (long to wide).
relocate - Move columns to a new position, keeping their values and every other column.
rename - Rename columns, leaving every other column and the column order unchanged.
select - Keep only the named columns, in the given order.
semi-join - Keep the rows of x that have a match in y, adding no columns.
slice-max - Keep the n rows with the largest value of col.
slice-min - Keep the n rows with the smallest value of col.
summarise - Collapse each group of rows to a single row of named aggregations.

Formatters

format-comma - Shorthand for format-number(big-mark: ",").
format-currency - Format a numeric break as currency.
format-lower - Lower-case a string break (ASCII letters only).
format-number - Format a numeric break with optional thousands separator and decimals.
format-percent - Format a numeric break as a percentage.
format-scientific - Format a numeric break in scientific notation as Typst math.
format-title - Title-case a string break: capitalise the first letter of each space-separated word.
format-upper - Upper-case a string break (ASCII letters only).
format-wrap - Soft-wrap a long string by inserting a newline at word boundaries.

Summary functions

mean - Mean as a degenerate summary (y, ymin: y, ymax: y).
mean-cl-boot - Mean with a bootstrap percentile confidence interval.
mean-cl-normal - Mean with normal-approximation confidence interval.
mean-sd - Mean and standard-deviation band: mean ± multiplier * sd.
mean-se - Mean and standard-error band: mean ± multiplier * se.
median - Median as a degenerate summary (y, ymin: y, ymax: y).
median-hilow - Median plus a central interval covering conf proportion of the data.
quantile - Single quantile as a degenerate summary (y, ymin: y, ymax: y).
quantiles - Three quantiles packed into the standard summary shape.

Scales

colour-mix - Blend two colours.
expand-limits - Ensure the trained domain includes the supplied values without replacing it.
scales - Bind scale specifications to aesthetics.

Breaks

breaks-extended - Round breaks from the extended Wilkinson search.
breaks-pretty - Round breaks at roughly the requested count.
breaks-quantile - Breaks at sample quantiles of the data.
breaks-width - Breaks spaced a fixed distance apart.

Colour and fill scales

scale-brewer - Discrete ColorBrewer colour/fill scale.
scale-distiller - Continuous ColorBrewer colour/fill scale (distiller).
scale-fermenter - Binned ColorBrewer colour/fill scale (fermenter).
scale-gradient - Two-colour continuous gradient colour/fill scale.
scale-gradient2 - Diverging three-colour gradient colour/fill scale.
scale-gradientn - N-colour continuous gradient colour/fill scale.
scale-grey - Discrete greyscale colour/fill scale.
scale-hue - Discrete evenly-spaced HCL hue colour/fill scale.
scale-okabe-ito - Discrete Okabe-Ito colourblind-safe colour/fill scale.
scale-steps - Binned two-colour gradient colour/fill scale (steps).
scale-steps2 - Binned diverging three-colour gradient colour/fill scale (steps2).
scale-stepsn - Binned N-colour gradient colour/fill scale (stepsn).
scale-viridis-b - Binned viridis colour/fill scale.
scale-viridis-c - Continuous viridis colour/fill scale.
scale-viridis-d - Discrete viridis colour/fill scale.

Generic scales

scale-binned - Binned scale that quantises a continuous variable into n-breaks bins.
scale-continuous - Continuous scale for any continuous aesthetic.
scale-discrete - Discrete scale for any categorical aesthetic.
scale-identity - Identity scale: use each row’s value as the visual output directly.
scale-manual - Manual discrete scale: supply a per-level array of output values.

Palettes

brewer-palette - Look up a ColorBrewer palette by name.
okabe-ito - Okabe-Ito colour-vision-deficiency-safe qualitative palette.

Position scales

scale-date - Temporal position scale formatting axis labels as dates (x or y).
scale-datetime - Temporal position scale formatting axis labels as datetimes (x or y).
scale-log10 - Position scale on a base-10 log axis (x or y).
scale-reverse - Position scale with the axis direction reversed (x or y).
scale-sqrt - Position scale on a square-root axis (x or y).
scale-time - Temporal position scale formatting axis labels as times (x or y).

Secondary axes

dup-axis - Duplicate the primary axis on the opposite side of the panel.
sec-axis - Secondary axis derived from the primary through a transformation.

Size scales

scale-area - Area-proportional continuous size scale.
scale-binned-area - Binned area-proportional size scale.
scale-radius - Linear-radius continuous size scale.

Coord

coord-cartesian - Cartesian coordinate system with optional panel clipping.
coord-fixed - Cartesian coordinate system with a fixed data-unit aspect ratio.
coord-flip - Cartesian coordinate system with the x and y axes swapped at render time.
coord-radial - Radial coordinate system.
coord-transform - Transform the displayed coordinates after statistics have run.

Positions

position-beeswarm - Density-shaped per-row offset on x.
position-dodge - Dodge position adjustment: place grouped marks side by side.
position-fill - Fill position adjustment: stack and normalise each x bucket to sum = 1.
position-identity - Identity position adjustment: no offset applied to any row.
position-jitter - Random per-row offset on x and y.
position-jitterdodge - Combined dodge then jitter position adjustment.
position-nudge - Shift every row’s x and y by a fixed amount in data units.
position-stack - Stack position adjustment: cumulate y per x bucket.

Themes

Complete themes

theme-bw - Black-and-white theme: white panel, black axes, light grey grid.
theme-classic - Classic theme: white panel, axis borders, no gridlines.
theme-dark - Dark theme: dark grey panel, white grid, dark axis text.
theme-grey - Grey theme: light grey panel with white gridlines.
theme-light - Light theme: light grey panel, white grid, soft grey axes.
theme-linedraw - Linedraw theme: white panel, strong black axes, very faint grid.
theme-minimal - Minimal theme: white panel, light grey gridlines, no axis lines.
theme-void - Void theme: no axes, no grid, no panel background.

Modify a theme

theme - Build a custom theme from per-element overrides.
theme-get - Get the current global default theme.
theme-set - Set the global default theme for all subsequent plots.

Sub-theme accessors

theme-sub-axis - Shortcut for both axes’ title, text, line, and ticks.
theme-sub-axis-bottom - Shortcut for the bottom x axis only.
theme-sub-axis-left - Shortcut for the left y axis only.
theme-sub-axis-right - Shortcut for the right y axis only.
theme-sub-axis-top - Shortcut for the top x axis only.
theme-sub-axis-x - Shortcut for both x axes (top + bottom).
theme-sub-axis-y - Shortcut for both y axes (left + right).
theme-sub-legend - Shortcut for legend text and title.
theme-sub-panel - Shortcut for panel grid and background.
theme-sub-plot - Shortcut for plot title, subtitle, caption, and outer margin.
theme-sub-strip - Shortcut for facet strip text and background.

Theme elements

element-blank - Blank element: hides the corresponding theme element.
element-geom - Layer-default aesthetics shared across geoms.
element-line - Line element: colour and stroke thickness.
element-rect - Rectangle element: fill, outline colour, stroke thickness, and per-side margins. inset is honoured on plot-background (Typst block(inset:) pads the content inward, and grows the painted fill outward past it when a fill or stroke is set) and on legend-background (grows the legend rect outward from the guide-stack bbox so the rectangle frames the legend with extra inner padding). panel-background and legend-bar ignore inset so the rect cannot bleed onto neighbours. outset reserves outer whitespace by widening the chrome slot on panel-background, legend-background, and legend-bar; on plot-background it wraps the rendered block in pad(...). On legend-background, the panel-facing outset side also widens the visible gap between panel and legend. On plot-background, both inset and outset apply whether or not a fill or stroke is set, so they reserve plot padding on their own. strip-background ignores both fields – the facet band has no surrounding slot to grow or reserve into.
element-text - Text element: font size, weight, colour, and angle.
element-tick - Tick element: a line element that also carries the tick mark length.
element-typst - Typst-markup text element: same fields as element-text plus automatic Typst-markup evaluation for plain strings reaching this surface.
margin - Per-side spacing record consumed by element-text / element-typst (text margin to neighbours) and element-rect (inset / outset offsets around the painted rectangle).