ribbon
Fills a band. It has two forms. The shape form, ribbon({ x, h }), draws one band per group from its rows: an area chart. The connector form fills a band between marks another flow placed (edge to edge): sankey ribbons and bands between bars. It takes the array of refs returned by selectAll().
const lakeTotals = Object.entries(_.groupBy(seafood, "lake")).map(
([lake, items]) => ({
lake,
count: items.reduce((sum, item) => sum + item.count, 0),
})
);
gf.layer([
gf
.chart(lakeTotals)
.flow(gf.spread({ by: "lake", dir: "x", spacing: 64 }))
.mark(gf.blank({ h: "count" }).name("points")),
gf.chart(gf.selectAll("points")).mark(gf.ribbon({ opacity: 0.6 })),
]).render(root, { h: 250, axes: true });Signature
// Shape form
ribbon({ x, h, fill?, stroke?, strokeWidth = 0, opacity?, blendMode = "normal", curve? })
ribbon({ y, w, fill?, stroke?, strokeWidth = 0, opacity?, blendMode = "normal", curve? })
// Connector form
ribbon({ stroke?, strokeWidth = 0, opacity?, blendMode = "normal", dir = "x", curve?, along?, from?, to?, w?, h?, emX?, emY? })Parameters
A filled band. Given x (with h) or y (with w), the shape form: the mark owns its rows and draws one band per group, from its baseline to h at each row's x (or to w at each row's y), sorted by it. Without them, the connector form: a band between the facing edges of consecutive marks another flow placed (sankey ribbons, bands between bars).
| Option | Type | Default | Description |
|---|---|---|---|
filter | Filter | string | A filter over this whole drawing: a Filter strategy (Filter.grayscale(), Filter.luminanceToAlpha()) or a raw CSS filter string ("blur(2px)", "url(#shadow)"). | |
fill | string | FieldExpr | Fill color of the band, or a field name or accessor for a color scale (constant within the band). Omitted, the band takes the color of the marks it connects. | |
stroke | string | FieldExpr | Stroke color of the band's outline, or a field name or accessor for a color scale (constant within the band). | |
strokeWidth | number | 0 | Stroke width in pixels. |
opacity | number | Opacity, 0 to 1. | |
blendMode | "normal" | "multiply" | "screen" | "overlay" | "color" | "luminosity" | "normal" | How bands mix where they overlap (CSS mix-blend-mode). |
dir | "x" | "y" | Connection axis. | |
curve | Curve | Screen-space band-edge shape, made by a call in the Curve family: Curve.linear(), Curve.bezier(), Curve.step(), Curve.monotone(), Curve.smooth() or Curve.catmullRom(). Curve.step() steps both edges, as a stepped area does. Curve.monotone() is piecewise monotone: between two neighboring points each edge only rises or only falls, so it never goes past either point, though the band still turns where the data turns (d3 curveMonotoneX, Vega-Lite interpolate "monotone"); Curve.smooth() is a rounder reading over the same parameter, and can go a little past a point; Curve.catmullRom() is a centripetal Catmull-Rom on screen and can overshoot. Omitted, it is Curve.monotone() on a homogeneous continuous connection axis, else a Curve.bezier() band. The shape form reads its curve over x (or y), so it takes Curve.linear(), Curve.step(), Curve.monotone() or Curve.smooth(), and Curve.monotone() when omitted. | |
from | string | ||
to | string | ||
along | string | Names a flow tier by its by field: that tier becomes the path tier (threading its groups in order) and every OTHER grouping tier splits. Omitted: the path tier is inferred from the flow shape. Naming a field that matches no tier, or using along where the mark doesn't fuse over this chart's own flow (a refs bag, or the pairwise from/to form), is an error. | |
emX | boolean | Blank-fusion anchor key: placed directly in .mark() position, ribbon(opts) elaborates to an invisible anchor tier (a blank() carrying just {w, h, emX, emY}) plus this connector — see the mark construct's doc. Ignored by ribbon itself. | |
emY | boolean | Blank-fusion anchor key — see emX. Ignored by ribbon itself. | |
w | number | string | FieldExpr | Shape form with y: the band's width at each row, an amount from its baseline (negative values extend the other way). Connector form: a blank-fusion anchor key (see emX), ignored by ribbon itself. | |
h | number | string | FieldExpr | Shape form with x: the band's height at each row, an amount from its baseline (negative values extend below it), so a stack can place it. Connector form: a blank-fusion anchor key (see emX), ignored by ribbon itself. | |
x | number | string | FieldExpr | Shape form: each row's x, a numeric or time column, a field expression, or an accessor. The band runs through the rows sorted by x, read between them as curve says; two rows of one group at one x are an error. Needs h. | |
y | number | string | FieldExpr | Shape form: each row's y, for a band that runs up the y axis. Needs w. | |
inset | number | Shape form: pixels the band is drawn in by from each end of its parameter, so the bands in the cells of a partition are drawn apart. Its values are not drawn in: the band stays on the baseline its data gives it, as a bar's data height is never inset. It changes only what is drawn: the band's box is the same. Not allowed on the connector form. |
Shape form
Given x, the ribbon draws one band per group, from 0 to h at each row's x. Given y, it draws from 0 to w at each row's y. The rows are sorted by x (or y), which must be a numeric or time column. Two rows of one group at the same x are an error: split them with group first. h may be negative, and the band then goes below the baseline. The curve defaults to Curve.monotone() and takes Curve.linear(), Curve.step(), Curve.monotone() or Curve.smooth().
chart(unemployment, { schema: { date: Unit.time() } })
.flow(group({ by: "series" }))
.mark(ribbon({ x: "date", h: "count", fill: "series", opacity: 0.5 }));A stack of shape-form ribbons is a stacked area. Each band keeps its thickness at every x, and sits on the bands before it. Outside its own rows a band has thickness 0.
chart(unemployment, { schema: { date: Unit.time() } })
.flow(stack({ by: "series", dir: "y" }))
.mark(ribbon({ x: "date", h: "count", fill: "series" }));A shape-form ribbon takes inset, a number of pixels. It is drawn in by inset from each end of its x, so the bands in the cells of a partition are drawn apart. Its values are not drawn in: the band stays on the baseline its data gives it. Only what is drawn changes: the band's box is the same.
Function channels
x and h (or y and w) may hold a function value, made with fun, in place of a column. The ribbon then has one parameter t, and reads every function channel at the same t. Its edges are the functions themselves, not curves through rows.
xholdsf.domain(), which istitself over the domain off.- Every function channel has the same domain, or it is an error that names both.
hmay be a number instead, a constant overt. A column beside a function is an error, since rows are not read att.curveis an error, since a function runs as it is.
const bump = fun((t) => 1 + Math.exp(-((t - 4) ** 2)), { domain: [0, 10] });
const wave = fun((t) => 1 + 0.6 * Math.sin(t), { domain: [0, 10] });
stack({ dir: "y" }, [
ribbon({ x: bump.domain(), h: bump }),
ribbon({ x: wave.domain(), h: wave }),
]);A stack of such ribbons keeps each band's thickness at every t, and takes a Baseline like any stacked area. It draws under a coordinate transform too.
Connector form
curve takes a member of the Curve family: Curve.linear(), Curve.bezier(), Curve.step(), Curve.monotone(), Curve.smooth() or Curve.catmullRom(). When curve is omitted, ribbon inspects the connection axis: over a homogeneous continuous axis (a stacked area / streamgraph sampling a continuous variable) it smooths the band edges with Curve.monotone() — matching its line sibling — and otherwise draws a bezier band, Curve.bezier() (the band equivalent of a straight line: the honest connector between discrete regions, as in a sankey or a categorical ribbon).
A ribbon drawn with Curve.monotone() or Curve.smooth() takes the knots of its curve the same way a line does, and both edges of the band use the same knots. Curve.step() steps both edges, as Vega-Lite's stepped area does. The Curve page compares the curves.
Like line, ribbon has a bag form (over a GoFishRef[], shown below) and a pairwise form ribbon({ from, to }) over rows whose from/to columns hold refs (one band per row, after resolve).
Default grouping
A ribbon fused into a flow — in .mark() position or as .layer() sugar over the previous tier's marks — splits at the flow's own grouping by default: one tier lays the band's path, and every other grouping in the flow splits it into separate bands. You don't restate the split — the flow one line up already declared it, and ribbon has no option that spells the split directly.
When you need a different path tier than the one inference would pick, name it with along: along: "year" finds the flow tier whose by is "year", makes it the path, and splits by every other grouping tier instead. Naming a field no tier groups by is an error. This doesn't apply to a ribbon drawn over an explicit refs bag (chart(selectAll(...))) or the pairwise { from, to } form — along is only meaningful when the ribbon fuses into a chart's own flow, and throws if used on either of those. A refs bag spells its split structurally instead, with an upstream flow(group({ by: "species" })).
Sugar: .layer(ribbon(...))
When the ribbon traces a chart's own marks, skip the two-layer selectAll recipe and chain .layer() on the builder — this is the canonical simple ribbon-chart spelling:
chart(seafood, { axes: true })
.flow(
spread({ by: "lake", dir: "x", spacing: 64 }),
stack({ by: field("species").sort("count"), dir: "y" })
)
.mark(rect({ h: "count", fill: "species" }))
.layer(ribbon({ opacity: 0.8 }))
.render(container, { h: 400 });No by needed: the stack({ by: "species" }) tier already told the flow how to group, so the ribbon splits into one band per species by default.
See .layer() for the full semantics, including the zBelow-by-default paint order and the desugaring to the explicit layer([...])
selectAllform below (which is still what you want to trace another chart's marks).
Sugar: .mark(ribbon(...)) (blank-fusion)
When there's no earlier tier at all — just raw data that needs both fresh anchors and a connector — place ribbon(...) directly in .mark() position and skip .layer() too. This is the fused spelling of the Ridgeline chart gallery example:
chart(seafood, { axes: true })
.flow(spread({ by: "lake", dir: "x", spacing: 64 }))
.mark(ribbon({ h: "count", opacity: 0.8 }));
// ...is sugar for the explicit two-tier form:
chart(seafood, { axes: true })
.flow(spread({ by: "lake", dir: "x", spacing: 64 }))
.mark(blank({ h: "count" }))
.layer(ribbon({ opacity: 0.8 }));A grouped flow fuses the same way, with no by needed — a streamgraph is one line:
chart(seafood, { axes: true })
.flow(
spread({ by: "lake", dir: "x", spacing: 64, alignment: "middle" }),
stack({ by: "species", dir: "y" })
)
.mark(ribbon({ h: "count", fill: "species", opacity: 0.8 }));fill here is a shared field name, homogeneous within each species group (the default split, above) — it resolves through the color scale per group, the same as it would if fill were declared on an explicit anchor blank().
See .layer()'s blank-fusion section for the full desugaring rule (the {w, h, emX, emY} anchor/connector key split, .name() chaining, and when the rule doesn't fire).
The w/h/emX/emY anchor channels are only meaningful when ribbon gets to synthesize its own anchors this way; passing them to a ribbon that instead connects already-drawn marks (an empty-scope chart() tier inside .layer(), or chart(selectAll(...))/chart(ref(...))) is an error, since there's nothing left for them to anchor.
Example
chart(selectAll("bars"))
.mark(ribbon({ opacity: 0.3 }))
.render(container, { w: 500, h: 300 });