treemap

Lays out children into a treemap: a 2D tiling of rectangles whose areas are proportional to a weight.

const items = [
  { name: "Action", value: 120 },
  { name: "Comedy", value: 80 },
  { name: "Drama", value: 160 },
  { name: "Sci-Fi", value: 60 },
  { name: "Horror", value: 40 },
];

// Each child gets its own rectangle; treemap assigns its (x,y,w,h).
// `size` is an explicit per-child weight array (one value per child, in
// child order) that drives each leaf's tile area.
gf.treemap(
  {
    size: items.map((d) => d.value),
    spacing: 2,
    padding: 2,
    round: true,
  },
  gf.map(items, (d) =>
    gf
      .rect({
        fill: gf.v(d.name),
        stroke: "white",
        strokeWidth: 1,
        rx: 3,
        ry: 3,
      })
      .label("name", { position: "center", color: "white", fontSize: 12 })(
      d,
      d.name
    )
  )
).render(root, { w: 520, h: 320 });

Inside .flow(...) (the fluent chart API), treemap({ by, size, ... }) partitions the rows itself, mirroring spread/group: by groups the flow's rows (a field name or a field(...) accessor carrying domain ops, e.g. field("genre").dropNulls()), and size — an entry-flagged channel — sums a field per group (or takes an explicit per-entry array) to weight each tile's area. See spread for the by/entry-flagged-channel pattern this mirrors.

Signature

treemap(options); // .flow() operator form
treemap(options, children); // combinator form

Parameters

treemap — Operator form

d3-hierarchy treemap layout over the flow's rows, fare/weight-proportional.

Option	Type	Default	Description
x	number | string | FieldExpr		Left edge of the box the treemap tiles into, in the parent's space (pixels). Omitted, the parent places the treemap.
y	number | string | FieldExpr		Top/bottom edge (y-up: bottom) of the box the treemap tiles into, in the parent's space (pixels). Omitted, the parent places the treemap.
w	number | string | FieldExpr		Width of the box the treemap tiles into; a number is pixels, a data-driven value scales through the layout. Omitted, the treemap fills the slot its parent allots.
h	number | string | FieldExpr		Height of the box the treemap tiles into; a number is pixels, a data-driven value scales through the layout. Omitted, the treemap fills the slot its parent allots.
dims	Record<string, AxisDimsValue>		The box the treemap tiles into, by axis name: x/y, or a name the enclosing coordinate space declares (polar theta/r, geo lon/lat). Each value is a position (like x) or an interval {min, center, max, size, embedded}.
by	string | FieldAccessor		Field to partition rows by (like spread/group); also accepts a field(...) accessor carrying domain ops (sort/reverse/bin/dropNulls). Without by, one leaf is emitted per row.
spacing	number	0	Gap between sibling tiles, in pixels.
padding	number	0	Inset around the outer edge of the treemap, in pixels.
round	boolean	true	Round pixel positions and sizes.
tile	object	{"kind":"squarify"}	The tiling strategy, made by a function call: squarify({ ratio? }), slice(), dice(), binary(), or sliceDice(). Each is one of d3-hierarchy's tiling methods.
sort	"asc" | "desc" | "none"	"desc"	Sort leaves by weight before layout.
size	number | string | FieldExpr		Per-leaf weight driving tile area (entry-flagged per split entry); a field name aggregates (sums by default) per group.

treemap — Combinator form

Low-level combinator form of treemap (single level). Same fields as the operator form (OPERATORS.treemap) plus key.

Option	Type	Default	Description
x	number | string | FieldExpr		Left edge of the box the treemap tiles into, in the parent's space (pixels). Omitted, the parent places the treemap.
y	number | string | FieldExpr		Top/bottom edge (y-up: bottom) of the box the treemap tiles into, in the parent's space (pixels). Omitted, the parent places the treemap.
w	number | string | FieldExpr		Width of the box the treemap tiles into; a number is pixels, a data-driven value scales through the layout. Omitted, the treemap fills the slot its parent allots.
h	number | string | FieldExpr		Height of the box the treemap tiles into; a number is pixels, a data-driven value scales through the layout. Omitted, the treemap fills the slot its parent allots.
dims	Record<string, AxisDimsValue>		The box the treemap tiles into, by axis name: x/y, or a name the enclosing coordinate space declares (polar theta/r, geo lon/lat). Each value is a position (like x) or an interval {min, center, max, size, embedded}.
by	string | FieldAccessor		Field to partition rows by (like spread/group); also accepts a field(...) accessor carrying domain ops (sort/reverse/bin/dropNulls). Without by, one leaf is emitted per row.
spacing	number	0	Gap between sibling tiles, in pixels.
padding	number	0	Inset around the outer edge of the treemap, in pixels.
round	boolean	true	Round pixel positions and sizes.
tile	object	{"kind":"squarify"}	The tiling strategy, made by a function call: squarify({ ratio? }), slice(), dice(), binary(), or sliceDice(). Each is one of d3-hierarchy's tiling methods.
sort	"asc" | "desc" | "none"	"desc"	Sort leaves by weight before layout.
size	number | string | FieldExpr		Per-leaf weight driving tile area (entry-flagged per split entry); a field name aggregates (sums by default) per group.
key	string		Internal per-node key override.

Strategies

tile holds the tiling strategy. You make a strategy with a function call. Each one is a tiling method from d3-hierarchy.

• squarify({ ratio? }) makes tiles as close as it can to the aspect ratio ratio, the longer side over the shorter side. ratio must be at least 1, and it does not choose between wide and tall tiles. It is the default. Without ratio, it uses d3's default, the golden ratio. squarify({ ratio: 1 }) aims for square tiles, which suits one circle per leaf.
• slice() puts the tiles in one column, stacked along y.
• dice() puts the tiles in one row, side by side along x.
• binary() splits the tiles into two halves of about equal weight, and repeats on each half.
• sliceDice() alternates between slice and dice by depth.

gf.treemap({ by: "genre", size: "gross", tile: gf.squarify({ ratio: 1 }) });

Notes

• The tile d3 places first sits at the top left. With the default sort: "desc", that is the largest tile.
• A treemap accepts a flat list of children; for multi-level treemaps, compose by nesting treemap(...) calls (or add a higher-level wrapper).
• In the combinator form, size is an explicit array, one weight per child in child order — it does not read back off each child's bound datum.