ribbon

Fills a band between data points (edge-to-edge) — areas, streamgraphs, and sankey ribbons. 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, { w: 400, h: 250, axes: true });

Signature

ribbon({ stroke?, strokeWidth = 0, opacity?, mixBlendMode = "normal", dir = "x", curve = "auto", along?, from?, to?, w?, h?, emX?, emY? })

Parameters

Option	Type	Description
stroke	string	Stroke color
strokeWidth	number	Stroke width
opacity	number	Opacity (0–1)
mixBlendMode	"normal" | "multiply"	Blend mode
dir	"x" | "y"	Direction axis
curve	"straight" | "bezier" | CurveSpec	Screen-space band shape; default "auto" (see below)
along	string	Names a flow tier by its by field (see Default grouping): that tier becomes the band's path, and every other grouping tier splits into separate bands. Usually omitted — the path tier is inferred from the flow shape. Naming a field that matches no tier, or using along on a ribbon that doesn't fuse into a chart's own flow (a refs bag, or the pairwise {from, to} form), throws.
from, to	string	Pairwise form: column names holding the two endpoint refs
w, h	number | string | Value<number> | FieldExpr	Ignored by ribbon itself. Blank-fusion anchor keys: read only when ribbon(opts) is placed directly in .mark() position, where they become the invisible anchor tier's blank({w, h, emX, emY}) opts — same channel-value shapes as a leaf mark's "size" channel (e.g. rect's h), including a field(...) pipeline like field("count").sum(). See .layer()'s blank-fusion section.
emX, emY	boolean	Ignored by ribbon itself. Blank-fusion anchor keys — see w/h above.

curve accepts the strings "straight" or "bezier", or a CurveSpec factory: straight(), bezier(), orthogonal(), arc({ direction: "up" | "down" }), or perfectArrows({ bow }). The default "auto" inspects the connection axis: over a homogeneous continuous axis (a stacked area / streamgraph sampling a continuous variable) it smooths the band edges with a centripetal Catmull-Rom spline — matching its line sibling — and otherwise draws a bezier band (the band equivalent of a straight line: the honest connector between discrete regions, as in a sankey or a categorical ribbon).

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, { w: 400, 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([...])

• selectAll form 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 Area chart and Ridgeline chart gallery examples:

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 });