Geoms

49 geoms

All geoms

• GeomPoint point · identity + identity Point geometry: one mark per data row. Use for scatter plots, dot plots, bubbles, and correlation views.
• GeomLine line · identity + identity Line geometry: connects points in x order, one line per group (groups derive from discrete aesthetics such as color, or from aes.group). Use for time series, trends, and line charts. With stat ecdf, pair with step curves; with stat bin (freqpoly alias), y is computed from counts/density; with stat connect, successive points expand into connection vertices.
• GeomPath path · identity + identity Path geometry: connects points in data (row) order within each group — unlike line, which sorts by x. Use for trajectories, loops, connected scatterplots, and ellipse rings (stat ellipse). With stat connect, successive points expand into connection vertices.
• GeomCol col · identity + stack Column geometry: one rectangle per data row, from the y baseline (zero) to the row's y value. Use when the data already contains the bar heights — prefer over GeomBar, which counts or bins.
• GeomBar bar · count + stack Bar geometry with counting or binning: one rectangle per distinct x value (stat count, discrete x) or per bin (stat bin, continuous x). Do not map aes.y — the stat computes it. Prefer GeomCol when bar heights are already in the data.
• GeomHistogram histogram · bin + stack · alias of bar Histogram geometry: a continuous x variable divided into bins, one bar per bin whose height is the count of rows (or the sum of aes.weight). Do not map aes.y — the bin stat computes it. Canonicalized by normalize() to a bar layer with stat bin.
• GeomFreqpoly freqpoly · bin + identity · alias of line Frequency polygon: continuous x binned like a histogram, drawn as a line through bin centers. Do not map aes.y — the bin stat computes it. Canonicalized by normalize() to a line layer with stat bin.
• GeomArea area · identity + stack Area geometry: a filled region from the y baseline (zero) to the y value, connected in x order per group. Use for stacked composition-over-time charts. With stat align, series with different x samples share a common grid for stack/fill.
• GeomRule rule · identity + identity Rule geometry: reference lines spanning the panel. Two forms: (1) annotation — set params.xintercept and/or params.yintercept to fixed data values and map neither aes.x nor aes.y; (2) data-driven — map exactly one of aes.x (vertical rules) or aes.y (horizontal rules) to a field. Never mix the forms in one layer.
• GeomHline hline · identity + identity · alias of rule Horizontal reference-line alias. Canonicalized by normalize() to a rule layer. Annotation form: set params.yintercept. Data-driven form: map aes.y (inherited plot x is dropped so the one-axis rule contract holds).
• GeomVline vline · identity + identity · alias of rule Vertical reference-line alias. Canonicalized by normalize() to a rule layer. Annotation form: set params.xintercept. Data-driven form: map aes.x (inherited plot y is dropped so the one-axis rule contract holds).
• GeomText text · identity + identity Text geometry: one label per data row at (x, y). No collision detection — labels draw exactly where placed. Requires x, y, and label channels.
• GeomLabel label · identity + identity Label geometry: text with a rounded rectangular background box. Requires x, y, and label channels. No collision detection.
• GeomSmooth smooth · smooth + identity Smooth geometry: a fitted trend line (with an optional confidence ribbon) over an x/y scatter, one fit per group. Use to reveal trends.
• GeomQuantile quantile · quantile + identity Quantile geometry: linear quantile regression lines (y ~ x) at one or more conditional quantiles of y, one line per quantile per group.
• GeomBoxplot boxplot · boxplot + dodge Box-and-whisker geometry: one box per x category (per group) summarizing the y distribution — hinges at the quartiles, whiskers to the furthest points within coef × IQR, outliers drawn individually.
• GeomDensity density · density + identity Density geometry: a smooth kernel density estimate of a continuous x variable, drawn as a filled area — a smoothed histogram alternative. One curve per group. Do NOT map aes.y — the density stat computes it.
• GeomErrorbar errorbar · identity + identity Errorbar geometry: a vertical range with caps at ymin and ymax, one per data row (identity stat) or per x group (summary stat).
• GeomLinerange linerange · identity + identity Linerange geometry: a vertical stem from ymin to ymax without end caps.
• GeomPointrange pointrange · identity + identity Pointrange geometry: vertical stem from ymin to ymax plus a point at (x, y).
• GeomCrossbar crossbar · identity + identity Crossbar geometry: a vertical interval box from ymin to ymax with a mid horizontal line at y.
• GeomRect rect · identity + identity Rectangle geometry: one rectangle per data row from mapped xmin/xmax/ymin/ymax edges. Use for arbitrary shaded regions and time bands.
• GeomTile tile · identity + identity Tile geometry: center-sized cells at (x, y) with optional width/height. Use for heatmaps and gridded categorical cells; supports stroke outlines.
• GeomRaster raster · identity + identity Raster geometry: equal-cell grid at (x, y) with fill; optimized dense heatmaps without per-cell strokes. Irregular spacing warns and suggests geom tile.
• GeomRibbon ribbon · identity + identity Ribbon geometry: a filled interval between two varying boundaries along a running coordinate. Map x+ymin+ymax (x orientation) or y+xmin+xmax (y orientation). Not a zero-baseline area.
• GeomSegment segment · identity + identity Segment geometry: one finite line per data row from (x, y) to (xend, yend). Unlike rule, endpoints are data-mapped and do not span the panel.
• GeomCount count · sum + identity Count geometry: point marks at unique (x, y) with size scaled by after_stat n (stat sum). Use for overplotting density on discrete or rounded coordinates.
• GeomViolin violin · ydensity + dodge Violin geometry: mirrored kernel density of continuous y at each discrete x (stat ydensity). One polygon per x×group. Default position dodge.
• GeomFunction function · function + identity Function geometry: evaluate a named portable function y = f(x) on a grid and draw a path. Requires params.fun; domain from params.xlim, mapped x, or peer layers.
• GeomPolygon polygon · identity + identity Polygon geometry: closed filled paths from (x, y) vertices in data/row order within each group. Groups form separate polygons. No x-sort (unlike line/area). Holes/subgroup omitted in v1.
• GeomHex hex · bin_hex + identity Hexagonal bin heatmap: partitions continuous x×y into a hexagonal lattice and maps fill to bin count by default.
• GeomBin2d bin_2d · bin_2d + identity 2D rectangular bin heatmap: partitions continuous x×y into a grid and maps fill to bin count by default. Empty bins are dropped unless params.drop is false.
• GeomAbline abline · identity + identity Abline geometry: one infinite reference line y = intercept + slope · x, clipped to the panel. Annotation form: fixed slope/intercept in params; does not inherit plot aes.
• GeomCurve curve · identity + identity Curve geometry: one curved connector per row from (x, y) to (xend, yend). Tessellated as a quadratic Bezier (curvature/angle/ncp). Requires field-mapped x, y, xend, and yend.
• GeomContour contour · contour + identity Contour geometry: isolines of a continuous z surface over a regular x×y grid. v1 draws open path polylines only (not filled bands).
• GeomDensity2d density_2d · density_2d + identity 2D density geometry: bivariate KDE isolines over continuous x and y. Open path contours.
• GeomDensity2dFilled density_2d_filled · density_2d_filled + identity 2D density filled bands: bivariate KDE closed isoline rings filled by density level. Open rings dropped. Defaults fill to after_stat(level).
• GeomDotplot dotplot · bindot + identity Dotplot geometry: stacked dots along a continuous x axis (histodot subset). Do not map aes.y — the bindot stat computes stack positions.
• GeomMap map · identity + identity Map geometry: join fortified region borders to value rows via aes.map_id and params.map. Renders closed filled paths per region.
• GeomSf sf · sf + identity Simple-features geometry: already-projected GeoJSON Geometry JSON strings in a data column. Point/line/polygon families (incl. GeometryCollection of one family) with even-odd holes; use coord_sf for fixed-aspect (CRS reproject deferred).
• GeomSfText sf_text · sf_coordinates + identity Simple-features text labels: places aes.label at representative geometry points (Multi* → one label per part; stat_sf_coordinates).
• GeomSfLabel sf_label · sf_coordinates + identity Simple-features labels with background boxes: places aes.label at representative geometry points with a measured rounded rect (Multi* → one label per part). color=ink+box stroke; fill=box background.
• GeomBlank blank · identity + identity Blank geometry: contributes mapped aesthetics to scale training and layout without drawing marks or hit targets. No channels are required; whatever is mapped trains its scale.
• GeomJitter jitter · identity + jitter · alias of point Jittered point alias. Canonicalized by normalize() to a point layer with position jitter. Configure jitter amount via positionParams.width/height/seed.
• GeomSpoke spoke · identity + identity Spoke geometry: one finite segment per row from (x, y) in direction angle (radians) with length radius. Endpoints are derived as xend = x + radius·cos(angle), yend = y + radius·sin(angle) in data space, then transformed like x/y. Requires continuous x and y.
• GeomRug rug · identity + identity Rug geometry: short ticks along panel edges for each observation. Map aes.x for bottom/top sides and/or aes.y for left/right sides.
• GeomStep step · identity + identity Step-line geometry: connect points with hv/vh/mid stairs. Same channels as line; ordered by x within groups.
• GeomQq qq · qq + identity Q–Q scatter: sample quantiles vs theoretical normal quantiles. Requires aes.sample.
• GeomQqLine qq_line · qq_line + identity Q–Q reference line: line through sample/theoretical quartile match, spanning the theoretical range of the Q–Q cloud. Requires aes.sample.

Shared layer props

Every geom shell accepts these props in addition to its own params. On the JSON layer they are top-level fields next to geom.

data

DataInput | readonly Record<string, unknown>[]

Optional layer-local data. When omitted, the layer inherits plot-level data. Inline rows, inline columns, or a named dataset.

aes

Aes

Optional aesthetic mapping for this layer. Merges over plot-level aes; set a channel to null to unset an inherited mapping.

stat

StatName (geom-specific)

Statistical transform applied before drawing. Omit to use the geom default (see defaultStat). Only values listed in allowedStats validate.

position

PositionName (geom-specific)

Position adjustment for how marks share coordinate space. Omit to use the geom default. Only values listed in allowedPositions validate.

positionParams

PositionParams

Parameters for jitter (width, height, seed) or nudge (x, y). Valid only when the layer allows those positions.

render

"svg" | "canvas" | "auto"

Optional per-layer render backend override. When omitted, the plot chooses.

inspect

false

Set false to exclude this layer from inspection: its marks never become tooltip, hover, or keyboard-traversal candidates. For decorative layers whose marks would otherwise capture the pointer.