Skip to content

group ​

Partitions data by a field and draws each partition's mark in one layer, which places nothing. Useful when you want a per-group enclosure that you can then style or reference, without imposing any spread/stack layout.

Signature ​

ts
group({ by, x?, y?, w?, h? });

Parameters ​

group — Operator form ​

Partition rows by by into one layer of the groups (no layout beyond grouping). Its box takes spread's x, y, w and h.

OptionTypeDefaultDescription
bystring | FieldAccessor | ChunkKeyRequired. Field to group rows by; also accepts a field(...) accessor carrying domain ops (sort/reverse/bin), or chunk(size) to group consecutive rows.
xnumber | string | FieldExprLeft edge of this operator's box, in the parent's space (pixels). Omitted, the parent places it.
ynumber | string | FieldExprStart edge on y (top where y reads top-down, bottom where it grows upward) of this operator's box, in the parent's space (pixels). Omitted, the parent places it.
wnumber | string | FieldExpr | LengthWidth of this operator's box: pixels, or a field name sizing it from data. Also percent(n), n percent of the room it is laid out in (its parent's, or the canvas), or fr(k), k shares of the room its nearest scope divides.
hnumber | string | FieldExpr | LengthHeight of this operator's box: pixels, or a field name sizing it from data. Also percent(n), n percent of the room it is laid out in (its parent's, or the canvas), or fr(k), k shares of the room its nearest scope divides.

group — Combinator form ​

OptionTypeDefaultDescription
xnumber | string | FieldExprLeft edge of this operator's box, in the parent's space (pixels). Omitted, the parent places it.
ynumber | string | FieldExprStart edge on y (top where y reads top-down, bottom where it grows upward) of this operator's box, in the parent's space (pixels). Omitted, the parent places it.
wnumber | string | FieldExpr | LengthWidth of this operator's box: pixels, or a field name sizing it from data. Also percent(n), n percent of the room it is laid out in (its parent's, or the canvas), or fr(k), k shares of the room its nearest scope divides.
hnumber | string | FieldExpr | LengthHeight of this operator's box: pixels, or a field name sizing it from data. Also percent(n), n percent of the room it is laid out in (its parent's, or the canvas), or fr(k), k shares of the room its nearest scope divides.

Example ​

ts
// One group per species, with the per-species mark inside.
.flow(group({ by: "species" }))
.mark(ribbon({ opacity: 0.7 }))

For the simple case — one ribbon or stream band per group, re-partitioning the marks a chart already drew — reach for a bare .layer(ribbon(...)) instead, with no by at all: a ribbon or line fused over a chart's own flow splits at the flow's own grouping by default (see ribbon's Default grouping). group() is for nested splits (composing with a connector's own by, or an explicit by override) and for operator pipelines generally — anywhere you need a named per-partition group without a connector mark driving the partitioning. group's own by reads refs when it runs after a selectAll, and a ref is read through its rows, so the bare field name works — by: "species":

ts
chart(selectAll("bars"))
  .flow(group({ by: "species" }))
  .mark(ribbon({ opacity: 0.8 }));

On a ref, a field resolves to a scalar only when every row in the ref's bag agrees on that field (homogeneity collapse); otherwise it is undefined. See spread → path-aware by for the full explanation.

For most cases you'll want spread or stack instead — they group and lay out. Reach for group when you need named per-partition groups (e.g. for selectAll or constraints) but don't want the children placed.