---
product: "AG Studio"
title: "Hierarchical Charts"
description: "Build treemap and sunburst charts in AG Studio to show nested part-to-whole data: which fields set each level and size, and what the tooltip shows."
framework: react
version: "3.1.0"
related:
    - title: "Bar and Column Charts"
      url: "https://www.ag-grid.com/studio/analysts/bar-and-column-charts/"
    - title: "Line and Area Charts"
      url: "https://www.ag-grid.com/studio/analysts/line-and-area-charts/"
    - title: "Combo Charts"
      url: "https://www.ag-grid.com/studio/analysts/combo-charts/"
    - title: "Scatter Charts"
      url: "https://www.ag-grid.com/studio/analysts/scatter-charts/"
    - title: "Polar Charts"
      url: "https://www.ag-grid.com/studio/analysts/polar-charts/"
    - title: "Proportional Charts"
      url: "https://www.ag-grid.com/studio/analysts/proportional-charts/"
    - title: "Progression Charts"
      url: "https://www.ag-grid.com/studio/analysts/progression-charts/"
    - title: "Statistical Charts"
      url: "https://www.ag-grid.com/studio/analysts/statistical-charts/"
llms: "https://www.ag-grid.com/studio/llms.txt"
---

# Hierarchical Charts

Hierarchical Charts show nested part-to-whole relationships, sized by value.

**Treemap Chart** nests rectangles to show a hierarchy of part-to-whole proportions, sized by value.

**Sunburst Chart** uses concentric rings to show the same kind of hierarchy, sized by value.

The example below shows revenue by product category and subcategory as both a Treemap and a Sunburst, comparing a rectangular layout against a radial one.

#### Hierarchical Chart

```ts
import {
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
  enableStudioDevValidations,
} from "ag-studio";
import { getData } from "./data.ts";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableStudioDevValidations();
}

const initialState: AgReportState = {
  pages: [
    {
      id: "page1",
      widgets: {
        "treemap-chart": {
          type: "treemap-chart",
          dataMapping: {
            categoryKey: [
              { id: "sales.category" },
              { id: "sales.subcategory" },
            ],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Treemap Chart",
            },
            subtitle: {
              enabled: true,
              text: "Annual revenue by product category and subcategory",
            },
          },
        },
        "sunburst-chart": {
          type: "sunburst-chart",
          dataMapping: {
            categoryKey: [
              { id: "sales.category" },
              { id: "sales.subcategory" },
            ],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Sunburst Chart",
            },
            subtitle: {
              enabled: true,
              text: "Annual revenue by product category and subcategory",
            },
          },
        },
      },
      widgetLayout: {
        "treemap-chart": { xTrack: 0, yTrack: 0, xSpan: 12, ySpan: 24 },
        "sunburst-chart": { xTrack: 12, yTrack: 0, xSpan: 12, ySpan: 24 },
      },
    },
  ],
  selectedPageId: "page1",
  panels: {
    filters: {
      collapsed: true,
    },
    data: {
      collapsed: true,
    },
    edit: {
      collapsed: true,
    },
  },
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
  data: getData(),
};

let studioApi: AgStudioApi;

// setup Studio after the page has finished loading
const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
```

[Live example: Hierarchical Chart](https://www.ag-grid.com/studio/examples/hierarchical-charts/hierarchical-chart/typescript/)

## Setup

Both Widgets take the same slots.

| Slot | Required | Accepts | What it does |
| --- | --- | --- | --- |
| Hierarchy Levels | Yes | One or more categories | Sets the levels of the hierarchy, outermost first. Each field nests inside the one before it. |
| Value | Yes | One numeric field | Sizes each tile (Treemap) or segment (Sunburst). A parent's size is the total of its children. |
| Tooltip | No | Any fields | Shows the fields in the tooltip without plotting them. |

### Hierarchy Levels

Each field in Hierarchy Levels adds a level to the hierarchy, and you can reorder the fields by dragging them. On a Sunburst Chart, the first level is the inner ring.

The example below plots the same revenue with one, two and three fields in Hierarchy Levels. Each row adds a level, with a Treemap on the left and a Sunburst on the right.

#### Hierarchy Levels

```ts
import {
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
  enableStudioDevValidations,
} from "ag-studio";
import { getData } from "./data.ts";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableStudioDevValidations();
}

const initialState: AgReportState = {
  pages: [
    {
      id: "page1",
      widgets: {
        "treemap-one": {
          type: "treemap-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.region" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Treemap: One Level",
            },
            subtitle: {
              enabled: true,
              text: "Hierarchy Levels: Region",
            },
          },
        },
        "sunburst-one": {
          type: "sunburst-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.region" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Sunburst: One Level",
            },
            subtitle: {
              enabled: true,
              text: "Hierarchy Levels: Region",
            },
          },
        },
        "treemap-two": {
          type: "treemap-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.region" }, { id: "sales.category" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Treemap: Two Levels",
            },
            subtitle: {
              enabled: true,
              text: "Hierarchy Levels: Region, then Category",
            },
          },
        },
        "sunburst-two": {
          type: "sunburst-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.region" }, { id: "sales.category" }],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Sunburst: Two Levels",
            },
            subtitle: {
              enabled: true,
              text: "Hierarchy Levels: Region, then Category",
            },
          },
        },
        "treemap-three": {
          type: "treemap-chart",
          dataMapping: {
            categoryKey: [
              { id: "sales.region" },
              { id: "sales.category" },
              { id: "sales.subcategory" },
            ],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Treemap: Three Levels",
            },
            subtitle: {
              enabled: true,
              text: "Hierarchy Levels: Region, Category, then Subcategory",
            },
          },
        },
        "sunburst-three": {
          type: "sunburst-chart",
          dataMapping: {
            categoryKey: [
              { id: "sales.region" },
              { id: "sales.category" },
              { id: "sales.subcategory" },
            ],
            valueKey: [{ id: "sales.revenue", aggregation: "sum" }],
            tooltipKey: [],
          },
          format: {
            title: {
              enabled: true,
              text: "Sunburst: Three Levels",
            },
            subtitle: {
              enabled: true,
              text: "Hierarchy Levels: Region, Category, then Subcategory",
            },
          },
        },
      },
      widgetLayout: {
        "treemap-one": { xTrack: 0, yTrack: 0, xSpan: 12, ySpan: 22 },
        "sunburst-one": { xTrack: 12, yTrack: 0, xSpan: 12, ySpan: 22 },
        "treemap-two": { xTrack: 0, yTrack: 22, xSpan: 12, ySpan: 22 },
        "sunburst-two": { xTrack: 12, yTrack: 22, xSpan: 12, ySpan: 22 },
        "treemap-three": { xTrack: 0, yTrack: 44, xSpan: 12, ySpan: 22 },
        "sunburst-three": { xTrack: 12, yTrack: 44, xSpan: 12, ySpan: 22 },
      },
    },
  ],
  selectedPageId: "page1",
  panels: {
    filters: {
      collapsed: true,
    },
    data: {
      collapsed: true,
    },
    edit: {
      collapsed: true,
    },
  },
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
  data: getData(),
};

let studioApi: AgStudioApi;

// setup Studio after the page has finished loading
const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
```

[Live example: Hierarchy Levels](https://www.ag-grid.com/studio/examples/hierarchical-charts/hierarchy-levels/typescript/)

### Tooltip

Fields in the Tooltip slot appear in the tooltip when you hover over a tile or segment, but do not change its size.

In the example below, the Setup tab is open beside a Treemap. Net Sales is in the Value slot, Region then Subcategory are in Hierarchy Levels, and Gross Sales is in the Tooltip slot. Hover over a tile to see its Gross Sales.

#### Tooltip

```ts
import {
  AgReportState,
  AgStudioApi,
  AgStudioProperties,
  createStudio,
  enableStudioDevValidations,
} from "ag-studio";
import { getData } from "./data.ts";

if (process.env.NODE_ENV !== "production") {
  // Enable extended validations only for development
  enableStudioDevValidations();
}

const initialState: AgReportState = {
  pages: [
    {
      id: "a",
      widgets: {
        "sales-treemap": {
          type: "treemap-chart",
          dataMapping: {
            categoryKey: [{ id: "sales.region" }, { id: "sales.subcategory" }],
            valueKey: [{ id: "sales.net_sales", aggregation: "sum" }],
            tooltipKey: [{ id: "sales.gross_sales", aggregation: "sum" }],
          },
          format: {
            title: {
              enabled: true,
              text: "Net Sales by Region and Subcategory",
            },
          },
          sort: [{ field: { id: "sales.subcategory" }, direction: "asc" }],
        },
      },
      widgetLayout: {
        "sales-treemap": {
          xTrack: 0,
          yTrack: 0,
          xSpan: 24,
          ySpan: 36,
        },
      },
      selection: { type: "widget", id: "sales-treemap" },
    },
  ],
  selectedPageId: "a",
};

const studioProperties: AgStudioProperties = {
  mode: "edit",
  initialState,
  panels: {
    edit: {
      right: ["edit"],
    },
  },
  data: getData(),
};

let studioApi: AgStudioApi;

// setup Studio after the page has finished loading
const studioDiv = document.querySelector<HTMLElement>("#myStudio")!;
studioApi = createStudio(studioDiv, studioProperties);
```

[Live example: Tooltip](https://www.ag-grid.com/studio/examples/hierarchical-charts/hierarchy-chart/typescript/)

## Format

Treemap and Sunburst Charts have no Format tab settings of their own, only the title and appearance settings every chart has.