Treemap Chart API
Complete API reference for the Treemap Chart, including data format, configuration options, custom parts, and context methods.
Data Format
Each dataset represents a group with a legend name and a tree of nodes. Leaf nodes have values; branch nodes aggregate child values.
type TreemapNode = {
label: string;
value?: number;
secondaryLabel?: string;
children?: TreemapNode[];
};
type TreemapDataset = {
legend: string;
visible?: boolean;
value?: number;
secondaryLabel?: string;
children?: TreemapNode[];
};
type TreemapData = {
datasets: TreemapDataset[];
};AG Style Config
Treemap
| Property | Type | Default | Description |
|---|---|---|---|
| treemap.groupGap | number | 8 | Gap between dataset groups in pixels. |
| treemap.nodeGap | number | 1 | Gap between nodes within a group in pixels. |
Group Title
| Property | Type | Default | Description |
|---|---|---|---|
| treemap.groupTitle.visible | boolean | true | Whether group title headers are visible. |
| treemap.groupTitle.fontSize | number | 12 | Group title font size. |
| treemap.groupTitle.color | string | "#2f3a46" | Group title text color. |
| treemap.groupTitle.gap | number | 6 | Gap between group title and nodes. |
Node
| Property | Type | Default | Description |
|---|---|---|---|
| treemap.node.minLabelWidth | number | 72 | Minimum node width in pixels for labels to appear. |
| treemap.node.minLabelHeight | number | 42 | Minimum node height in pixels for labels to appear. |
| treemap.node.dimOpacity | number | 0.38 | Opacity of non-hovered nodes when one is hovered. |
| treemap.node.labelColor | string | "#ffffff" | Node label text color. |
| treemap.node.secondaryLabelColor | string | "rgba(255,255,255,0.84)" | Secondary label text color. |
| treemap.node.hoverShadowColor | string | "rgba(0,0,0,0.10)" | Shadow color on hovered nodes. |
Toast Style Config
Treemap
| Property | Type | Default | Description |
|---|---|---|---|
| treemap.groupGap | number | 0 | Gap between dataset groups in pixels. |
| treemap.nodeGap | number | 0 | Gap between nodes within a group in pixels. |
| treemap.dividerColor | string | "transparent" | Color of divider lines between nodes. |
Group Title
| Property | Type | Default | Description |
|---|---|---|---|
| treemap.groupTitle.visible | boolean | false | Whether group title headers are visible. |
Node
| Property | Type | Default | Description |
|---|---|---|---|
| treemap.node.minLabelWidth | number | 72 | Minimum node width in pixels for labels to appear. |
| treemap.node.minLabelHeight | number | 42 | Minimum node height in pixels for labels to appear. |
| treemap.node.labelColor | string | "#ffffff" | Node label text color. |
| treemap.node.secondaryLabelColor | string | "rgba(255,255,255,0.86)" | Secondary label text color. |
| treemap.node.hoverBorderColor | string | "white" | Border color on hovered nodes. |
| treemap.node.hoverBorderWidth | number | 4 | Border width on hovered nodes. |
| treemap.node.hoverShadowColor | string | "rgba(0,0,0,0.3)" | Shadow color on hovered nodes. |
| treemap.node.hoverScale | number | 1.02 | Scale factor when a node is hovered. |
Custom Parts
Override any visual element by providing a custom builder function: (args, context) => Widget
| Part | Args | Description |
|---|---|---|
| layout | { title: Widget; legends: Widget[]; plot: Widget } | Top-level layout composing title, legends, and the plot area. |
| plot | { treemap: Widget; tooltipArea: Widget } | The plot area with treemap and tooltip. |
| title | undefined | Chart title element. |
| legend | { name: string; index: number; isVisible: boolean } | Individual legend item. |
| treemap | { tree: Widget } | The treemap container. |
| group | { title: Widget; nodes: Widget; legend: string; index: number; color: string; ratio: number; isHovered: boolean } | A dataset group with title and nodes. |
| groupTitle | { legend: string; index: number } | Group title header. |
| nodes | { tree: Widget; legend: string; index: number } | Container for nodes within a group. |
| node | { label: string; secondaryLabel?: string; value: number; legend: string; groupIndex: number; index: number; color: string; ratio: number; groupRatio: number; isHovered: boolean; dataLabel: Widget } | Individual treemap node rectangle. |
| dataLabel | { label: string; secondaryLabel?: string; value: number; legend: string; groupIndex: number; index: number; ratio: number; groupRatio: number; isHovered: boolean } | Data label inside a treemap node. |
| tooltip | { label: string; items: { legend: string; color: string; value: number }[] } | Tooltip content widget. |
| tooltipArea | { tooltip: Widget | null; hoveredNode: TreemapHoveredNodeRect | null } | Tooltip positioning area. |
Context: TreemapContext
Available in every custom builder via the second argument.
| Name | Type | Kind | Description |
|---|---|---|---|
| data | TreemapResolvedData | property | Current resolved chart data (filtered by hidden series). |
| legends | string[] | property | All dataset legend names. |
| totalValue | number | property | Sum of all visible dataset values. |
| width | number | property | Current chart width in pixels. |
| height | number | property | Current chart height in pixels. |
| hiddenSeries | ReadonlySet<string> | property | Set of currently hidden series names. |
| hoveredNode | TreemapHoveredNode | null | property | Currently hovered node info. |
| config | TConfig | property | The resolved chart configuration object. |
| isSeriesVisible(name) | (name: string) => boolean | method | Check if a series is currently visible. |
| toggleSeries(name) | (name: string) => void | method | Toggle visibility of a series. |
| showSeries(name) | (name: string) => void | method | Show a hidden series. |
| hideSeries(name) | (name: string) => void | method | Hide a visible series. |
| showAllSeries() | () => void | method | Show all hidden series. |
| hoverNode(node, anchorKey) | (node: TreemapHoveredNode, anchorKey: GlobalKey) => void | method | Set hover state on a node. |
| unhoverNode(key) | (key: string) => void | method | Clear hover if the specified node is currently hovered. |
| unhoverAllNodes() | () => void | method | Clear all node hover state. |
| isNodeHovered(key) | (key: string) => boolean | method | Check if a specific node is hovered. |
| isGroupHovered(groupIndex) | (groupIndex: number) => boolean | method | Check if any node in a group is hovered. |
| getGroupLayout(size) | (size: TreemapLayoutSize) => TreemapLayout | null | method | Compute layout for dataset groups. |
| getNodeLayout(nodes, size) | (nodes: TreemapResolvedNode[], size: TreemapLayoutSize) => TreemapLayout | null | method | Compute layout for nodes within a group. |
| setSize(width, height) | (width: number, height: number) => void | method | Update chart dimensions. |
Custom Part Example
import { ToastTreemapChart } from "@/components/flitter/charts/toast-treemap-chart";
<ToastTreemapChart
data={data}
config={{
treemap: {
nodeGap: 2,
node: { hoverScale: 1.05 },
},
}}
/>