Charts

Treemap

A space-filling treemap chart for visualizing hierarchical or categorical proportions.

import { Treemap } from "metricui";

Use Treemap for part-to-whole analysis of hierarchical data — budget breakdowns, disk usage, traffic by section. Supports hierarchical Nivo data or flat DataRow[] with automatic aggregation. For non-hierarchical part-to-whole, consider DonutChart.

Basic Example

Department Budget Breakdown

<Treemap
  data={{
    name: "Company",
    children: [
      { name: "Engineering", children: [
        { name: "Frontend", value: 420000 },
        { name: "Backend", value: 380000 },
        { name: "Platform", value: 290000 },
        { name: "QA", value: 140000 },
      ]},
      { name: "Sales", children: [
        { name: "Enterprise", value: 310000 },
        { name: "Mid-Market", value: 240000 },
        { name: "SDR Team", value: 180000 },
      ]},
      // ...
    ],
  }}
  title="Department Budget Breakdown"
  format="currency"
  height={350}
/>

Custom Tiling

The tile prop controls the layout algorithm. Options: squarify (default), binary, slice, dice, sliceDice.

Binary Tiling

<Treemap
  data={budgetData}
  title="Binary Tiling"
  tile="binary"
  format="currency"
  height={300}
/>

Flat Row Mode

Pass flat DataRow[] with index and value props. The component wraps them in a single-level hierarchy automatically.

Website Traffic by Page

<Treemap
  data={[
    { page: "/pricing", views: 48200 },
    { page: "/docs", views: 36100 },
    { page: "/blog", views: 28400 },
    { page: "/features", views: 22800 },
    { page: "/about", views: 14600 },
    { page: "/changelog", views: 11200 },
    { page: "/contact", views: 8900 },
    { page: "/careers", views: 6400 },
  ]}
  index="page"
  value="views"
  title="Website Traffic by Page"
  format="number"
  height={300}
/>

Props

Prop	Type	Default	Description
`data`	`TreemapDatum \| DataRow[]`	—	Hierarchical Nivo data (name/value/children) OR flat DataRow[] (aggregated via index + value).
`index`	`string`	`"name"`	Category field name when using flat DataRow[] input.
`value`	`string`	`"value"`	Value field name when using flat DataRow[] input.
`title`	`string`	—	Chart card title.
`subtitle`	`string`	—	Chart card subtitle.
`description`	`string \| React.ReactNode`	—	Description popover content.
`footnote`	`string`	—	Footnote.
`action`	`React.ReactNode`	—	Action slot.
`height`	`number`	`300`	Chart height in px.
`colors`	`string[]`	—	Tile colors. Default: theme series palette.
`format`	`FormatOption`	—	Format for value labels and tooltips.
`tile`	`"squarify" \| "binary" \| "slice" \| "dice" \| "sliceDice"`	`"squarify"`	Tiling algorithm.
`innerPadding`	`number`	`2`	Padding between sibling tiles (px).
`outerPadding`	`number`	`4`	Padding around the root (px).
`labelSkipSize`	`number`	`24`	Skip labels on tiles smaller than this (px).
`animate`	`boolean`	`true`	Enable/disable animation.
`legend`	`boolean \| LegendConfig`	—	Legend configuration. Default: shown.
`crossFilter`	`boolean \| { field?: string }`	—	Enable cross-filtering. true uses index as the field.
`drillDown`	`true \| ((event: TreemapClickEvent) => React.ReactNode)`	—	Drill-down. true = auto table, function = custom content.
`drillDownMode`	`"slide-over" \| "modal"`	`"slide-over"`	Drill-down presentation mode.
`tooltipHint`	`boolean \| string`	—	Tooltip action hint.
`variant`	`CardVariant`	—	Card variant.
`dense`	`boolean`	—	Compact layout.
`className`	`string`	—	Additional CSS class names.
`classNames`	`{ root?: string; header?: string; chart?: string; body?: string; legend?: string }`	—	Sub-element class name overrides.
`id`	`string`	—	HTML id attribute.
`data-testid`	`string`	—	Test id.
`loading`	`boolean`	—	Loading state.
`empty`	`EmptyState`	—	Empty state configuration.
`error`	`ErrorState`	—	Error state configuration.
`stale`	`StaleState`	—	Stale data indicator.

Data Shape

// Hierarchical format
interface TreemapDatum {
  name: string;
  value?: number;
  children?: TreemapDatum[];
}

// Flat-row format (converted via index + value props)
type DataRow = { name: string; value: number; [key: string]: unknown };

Notes

Uses forwardRef.
Accepts two data modes: hierarchical TreemapDatum (name/value/children) or flat DataRow[] with index + value props.
Only leaf nodes are rendered. The root node is used as a container.
The squarify algorithm (default) produces the most readable layouts. Use binary for more uniform shapes.
labelSkipSize prevents label clutter on small tiles — increase it for dense datasets.
The aiContext prop (inherited from BaseComponentProps) adds business context for AI Insights analysis. See the AI Insights guide for details.