TreeMap

Part-to-whole treemap with optional nesting to any depth.

stable

Quick Preview

Portfolio mix

Share of listings by area

Usage

import { ChartCard, ChartHeader, ChartTitle } from "@giddaa-housing/ui/chart";
import { TreeMap } from "@giddaa-housing/ui/tree-map";

<ChartCard>
  <ChartHeader><ChartTitle>Portfolio mix</ChartTitle></ChartHeader>
  <TreeMap
    data={[
      { area: "Lekki", count: 42 },
      { area: "Ikoyi", count: 28 },
      { area: "Yaba", count: 18 },
    ]}
    categoryKey="area"
    valueKey="count"
    ariaLabel="Share of listings by area"
  />
</ChartCard>

TreeMap sizes one tile per row by valueKey. Tiles show their name and share when they fit. A color-key legend sits to the right (legend="bottom" or false to move or hide it). Compose title and description with ChartCard.

Examples

Default

Portfolio mix

Share of listings by area

Nested

groupKey takes one field or a path of fields from outermost to innermost, so a treemap can nest to any depth. Color and the legend follow the top-level group; tooltips show the full path.

Holdings

Region › area › property type

<TreeMap
  data={holdings}
  categoryKey="type"
  valueKey="count"
  groupKey={["region", "area"]}
  ariaLabel="Holdings by region, area, and property type"
/>

Props

Prop/APITypeDefaultDescription
datareadonly T[]requiredOne row per tile.
categoryKeystring or number field of TrequiredField naming each tile.
valueKeynumeric field of TrequiredNonnegative value sized into each tile's area.
ariaLabelstringrequiredAccessible chart name.
groupKeyfield, or array of fields, of T-Nesting, from outermost to innermost.
colorKeystring field of Tpalette by top-level groupField holding a tile's CSS fill.
labelColorKeystring field of T-Field holding the in-tile label color on a custom fill.
size"sm" | "md" | "lg"inherited, otherwise "md"Plot and type scale (TREE_MAP_LAYOUT).
legend"right" | "bottom" | false"right"Color-key legend placement. Items toggle their tile, or their group when nested; the remaining shares are taken of what is still shown. A right legend wraps under the plot when the plot would be narrower than plotMinWidth.
plotMinWidthnumber240Narrowest the plot gets beside a right legend, in px.
labelsbooleantrueIn-tile name and share, hidden on tiles too small to fit them.
tooltipbooleantrueHover and keyboard tooltip.
formatValue(value: number) => stringgrouped numberTile values.
formatShare(share: number) => stringwhole percentTile label and tooltip shares; share is 0–1.
formatCategory(value: string | number) => stringStringTile and group names.
emptyMessageReactNode"No data to display"Shown when no valid tiles exist.
Chart host propssee Chart-height, initialWidth, ariaDescription, tooltipFooter, renderTooltipBody, callbacks, className, style.
createTreeMapDefinition(options)function-Same options without the legend; returns an extensible TanStack definition.
treeMapLabelColor(index)helper-Readable label color for a palette slot.

Accessibility

  • Provide a meaningful ariaLabel; focus the chart and use arrow keys to move between tiles.
  • Keep the legend and in-tile labels so groups are identified by text, not color alone.
  • Small tiles hide their labels; the tooltip always carries the name, value, and share.

On this page