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/API | Type | Default | Description |
|---|---|---|---|
data | readonly T[] | required | One row per tile. |
categoryKey | string or number field of T | required | Field naming each tile. |
valueKey | numeric field of T | required | Nonnegative value sized into each tile's area. |
ariaLabel | string | required | Accessible chart name. |
groupKey | field, or array of fields, of T | - | Nesting, from outermost to innermost. |
colorKey | string field of T | palette by top-level group | Field holding a tile's CSS fill. |
labelColorKey | string 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. |
plotMinWidth | number | 240 | Narrowest the plot gets beside a right legend, in px. |
labels | boolean | true | In-tile name and share, hidden on tiles too small to fit them. |
tooltip | boolean | true | Hover and keyboard tooltip. |
formatValue | (value: number) => string | grouped number | Tile values. |
formatShare | (share: number) => string | whole percent | Tile label and tooltip shares; share is 0–1. |
formatCategory | (value: string | number) => string | String | Tile and group names. |
emptyMessage | ReactNode | "No data to display" | Shown when no valid tiles exist. |
| Chart host props | see 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.