JavaScript ChartsSunburst Series

Version 14.2.0

A Sunburst Series is used to render hierarchical data structures or trees. Each node in the tree is represented by a segment on a radial circle, with the area of the sum of values.

Simple Sunburst Copy Link

main.ts

import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  SunburstSeriesModule,
} from "ag-charts-enterprise";
import { data } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  LegendModule,
  SunburstSeriesModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data,
  series: [
    {
      type: "sunburst",
      labelKey: "name",
    },
  ],
  title: {
    text: "Organisational Chart",
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

data.ts

export const data = [
  {
    name: "Mariah Vaughan",
    children: [
      {
        name: "Bushra Thomas",
        children: [
          { name: "Cyrus Henderson", children: [] },
          { name: "Dora Jordan", children: [] },
          { name: "Skyla Downs", children: [] },
          { name: "Elissa O'Sullivan", children: [] },
        ],
      },
      {
        name: "Craig Roman",
        children: [
          { name: "Martin Reid", children: [] },
          { name: "Joanna Key", children: [] },
        ],
      },
      {
        name: "Vincent Patterson",
        children: [
          { name: "Franklin Hernandez", children: [] },
          { name: "Lilian Zuniga", children: [] },
          { name: "Eliza Schneider", children: [] },
        ],
      },
      { name: "Caspar Mueller", children: [] },
      { name: "Annika Kim", children: [] },
      {
        name: "Aiza Jarvis",
        children: [
          { name: "Katerina Marshall", children: [] },
          {
            name: "Nannie Massey",
            children: [
              { name: "Abel Espinoza", children: [] },
              { name: "Rose Mckay", children: [] },
              { name: "Sana Winters", children: [] },
            ],
          },
        ],
      },
      {
        name: "Alan Burgess",
        children: [{ name: "Jaxon Jefferson", children: [] }],
      },
      { name: "Jay Suarez", children: [] },
    ],
  },
  {
    name: "Nathanael Villa",
    children: [
      { name: "Saira Sparks", children: [] },
      { name: "Stella Wyatt", children: [] },
      {
        name: "Carly O'Connor",
        children: [{ name: "Ieuan Charles", children: [] }],
      },
      { name: "Ariana Morales", children: [] },
    ],
  },
];

The Sunburst Series is designed to display a single series and is created using the sunburst series type.

{
    series: [
        {
            type: 'sunburst',
            labelKey: 'name',
        },
    ],
}

The data passed in should be an array of nodes, with each node optionally containing children.

const data = [
    {
        name: 'Mariah Vaughan',
        children: [
            {
                name: 'Bushra Thomas',
                children: [
                    { name: 'Cyrus Henderson' },
                    { name: 'Dora Jordan' },
                    { name: 'Skyla Downs' },
                    { name: "Elissa O'Sullivan" },
                ],
            },
        ],
        // ...
    },
    {
        name: 'Nathanael Villa',
        // ...
    },
];

The labelKey defines what will appear as the title for each sector.

Sizing Copy Link

By default, the segments corresponding to leaf nodes will have the same angle.

However, the Sunburst Series is best suited to providing size values to provide relative sizing between these sectors.

main.ts

import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  SunburstSeriesModule,
} from "ag-charts-enterprise";
import { data } from "./data";

const gdpFormatter = new Intl.NumberFormat("en-US", {
  useGrouping: true,
  minimumFractionDigits: 2,
  maximumFractionDigits: 2,
});
ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  LegendModule,
  SunburstSeriesModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data: data,
  series: [
    {
      type: "sunburst",
      labelKey: "name",
      sizeKey: "gdp",
      sizeName: "GDP",
    },
  ],
  title: {
    text: "Top 10 countries by GDP",
  },
  subtitle: {
    text: "2023",
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

data.ts

export const data = [
  {
    name: "Americas",
    children: [
      { name: "United States", gdp: 26.949, gdpChange: 0.06 },
      { name: "Canada", gdp: 2.117, gdpChange: 0 },
      { name: "Brazil", gdp: 2.126, gdpChange: 0.11 },
    ],
    gdpChange: 0.09,
  },
  {
    name: "Asia",
    children: [
      { name: "China", gdp: 17.7, gdpChange: 0 },
      { name: "Japan", gdp: 4.23, gdpChange: 0 },
      { name: "India", gdp: 4.0, gdpChange: 0.2 },
    ],
    gdpChange: 0.05,
  },
  {
    name: "Europe",
    children: [
      {
        name: "EU",
        children: [
          { name: "Germany", gdp: 4.429, gdpChange: 0.09 },
          { name: "France", gdp: 3.049, gdpChange: 0.1 },
          { name: "Italy", gdp: 2.186, gdpChange: 0.09 },
        ],
        gdpChange: 0.08,
      },
      { name: "United Kingdom", gdp: 3.332, gdpChange: 0.09 },
    ],
    gdpChange: 0.08,
  },
];

The sizeKey can be used to provide a numeric value to adjust the relative sizing. Additionally, the optional sizeName property can be set to set the title that appears next to the value in tooltips.

{
    series: [
        {
            type: 'sunburst',
            labelKey: 'name',
            sizeKey: 'gdp',
            sizeName: 'GDP',
        },
    ],
}

Colour Scale Copy Link

Use colorScale to control how colorKey values map to colours.

main.ts

import {
  AgCharts,
  AgStandaloneChartOptions,
  AgSunburstSeriesOptions,
  GradientLegendModule,
  LegendModule,
  ModuleRegistry,
  SunburstSeriesModule,
} from "ag-charts-enterprise";
import { data } from "./data";

ModuleRegistry.registerModules([
  GradientLegendModule,
  LegendModule,
  SunburstSeriesModule,
]);

const options: AgStandaloneChartOptions = {
  data: data,
  series: [
    {
      type: "sunburst",
      labelKey: "name",
      colorKey: "gdpChange",
      colorName: "Change",
      colorScale: {
        fills: [{ color: "tomato" }, { color: "gold" }, { color: "seagreen" }],
      },
    },
  ],
  legend: {
    enabled: false,
  },
  gradientLegend: {
    enabled: true,
  },
  title: {
    text: "Top Economies by GDP",
  },
  subtitle: {
    text: "2023 — Year-on-year change",
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

function modeChange(event: Event) {
  const mode = (event.target as HTMLInputElement).value as "stops" | "gradient";
  const series = options.series![0] as AgSunburstSeriesOptions;
  if (mode === "stops") {
    series.colorScale = {
      mode: "discrete",
      fills: [
        { color: "tomato", stop: -0.01, name: "Decline" },
        { color: "gold", stop: 0.01, name: "Flat" },
        { color: "seagreen", name: "Growth" },
      ],
    };
    options.legend = { enabled: true };
    options.gradientLegend = { enabled: false };
  } else {
    series.colorScale = {
      fills: [{ color: "tomato" }, { color: "gold" }, { color: "seagreen" }],
    };
    options.legend = { enabled: false };
    options.gradientLegend = { enabled: true };
  }

  chart.update(options);
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).modeChange = modeChange;
}

data.ts

export const data = [
  {
    name: "Americas",
    children: [
      { name: "United States", gdp: 26.949, gdpChange: 0.06 },
      { name: "Canada", gdp: 2.117, gdpChange: -0.08 },
      { name: "Brazil", gdp: 2.126, gdpChange: 0.15 },
      { name: "Mexico", gdp: 1.322, gdpChange: -0.12 },
    ],
    gdpChange: 0.03,
  },
  {
    name: "Asia",
    children: [
      { name: "China", gdp: 17.7, gdpChange: -0.04 },
      { name: "Japan", gdp: 4.23, gdpChange: -0.15 },
      { name: "India", gdp: 4.0, gdpChange: 0.2 },
      { name: "South Korea", gdp: 1.721, gdpChange: -0.06 },
    ],
    gdpChange: -0.01,
  },
  {
    name: "Europe",
    children: [
      {
        name: "EU",
        children: [
          { name: "Germany", gdp: 4.429, gdpChange: -0.1 },
          { name: "France", gdp: 3.049, gdpChange: 0.1 },
          { name: "Italy", gdp: 2.186, gdpChange: 0.12 },
        ],
        gdpChange: 0.04,
      },
      { name: "United Kingdom", gdp: 3.332, gdpChange: -0.03 },
    ],
    gdpChange: 0.01,
  },
];

{
    series: [
        {
            type: 'sunburst',
            labelKey: 'name',
            colorKey: 'gdpChange',
            colorName: 'Change',
            colorScale: {
                mode: 'discrete',
                fills: [
                    { color: 'tomato', stop: -0.01, name: 'Decline' },
                    { color: 'gold', stop: 0.01, name: 'Flat' },
                    { color: 'seagreen', name: 'Growth' },
                ],
            },
        },
    ],
}

In this example:

Use the toggle to switch between discrete mode with named stops shown in a category legend, and a continuous gradient shown in a gradient legend.

See the Colour Scale page for the full range of colour scale options including discrete mode, named stops, fixed domains, missing data, and gradient legend customisation.

Labels Copy Link

All segments can contain both labels and secondary labels, which can be shrunk to fit in the available space.

main.ts

import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  SunburstSeriesModule,
} from "ag-charts-enterprise";
import { data } from "./data";

const gdpFormatter = new Intl.NumberFormat("en-US", {
  minimumFractionDigits: 2,
  maximumFractionDigits: 2,
});
const percentageFormatter = new Intl.NumberFormat("en-US", {
  style: "percent",
  signDisplay: "always",
});
ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  LegendModule,
  SunburstSeriesModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data: data,
  series: [
    {
      type: "sunburst",
      labelKey: "name",
      sizeKey: "gdp",
      sizeName: "GDP",
      secondaryLabelKey: "gdpChange",
      label: {
        fontSize: 14,
        minimumFontSize: 9,
        spacing: 2,
      },
      secondaryLabel: {
        formatter: ({ value }) =>
          value != null ? percentageFormatter.format(value) : undefined,
      },
      padding: 3,
    },
  ],
  title: {
    text: "Top 10 countries by GDP",
  },
  subtitle: {
    text: "2023",
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

data.ts

export const data = [
  {
    name: "Americas",
    children: [
      { name: "United States", gdp: 26.949, gdpChange: 0.06 },
      { name: "Canada", gdp: 2.117, gdpChange: 0 },
      { name: "Brazil", gdp: 2.126, gdpChange: 0.11 },
    ],
    gdpChange: 0.09,
  },
  {
    name: "Asia",
    children: [
      { name: "China", gdp: 17.7, gdpChange: 0 },
      { name: "Japan", gdp: 4.23, gdpChange: 0 },
      { name: "India", gdp: 4.0, gdpChange: 0.2 },
    ],
    gdpChange: 0.05,
  },
  {
    name: "Europe",
    children: [
      {
        name: "EU",
        children: [
          { name: "Germany", gdp: 4.429, gdpChange: 0.09 },
          { name: "France", gdp: 3.049, gdpChange: 0.1 },
          { name: "Italy", gdp: 2.186, gdpChange: 0.09 },
        ],
        gdpChange: 0.08,
      },
      { name: "United Kingdom", gdp: 3.332, gdpChange: 0.09 },
    ],
    gdpChange: 0.08,
  },
];

{
    series: [
        {
            type: 'sunburst',
            labelKey: 'name',
            secondaryLabelKey: 'gdpChange',
            sizeKey: 'gdp',
            sizeName: 'GDP',
            label: {
                fontSize: 14,
                minimumFontSize: 9,
                spacing: 2,
            },
            secondaryLabel: {
                formatter: ({ value }) => (value != null ? percentageFormatter.format(value) : undefined),
            },
            padding: 3,
        },
    ],
}

In this configuration:

fontSize sets the size of the font.
minimumFontSize will enable the font size to shrink down to the given value if there is not enough space.
spacing controls the amount of space below a label.
padding adds space between the edge of a sector and its contents.
formatter allows customising the value of a label using a function.

Inner Circle Copy Link

Provide an innerRadiusRatio to display additional information in the centre of the chart.

main.ts

import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  SunburstSeriesModule,
} from "ag-charts-enterprise";
import { data } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  LegendModule,
  SunburstSeriesModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data,
  series: [
    {
      type: "sunburst",
      labelKey: "name",
      sizeKey: "budget",
      sizeName: "Budget",
      innerRadiusRatio: 0.4,
      innerCircle: {
        fill: "#c9fdc9",
      },
      innerLabels: [
        {
          text: "Total Budget",
          fontSize: 12,
          color: "gray",
        },
        {
          text: "$1.3M",
          fontSize: 24,
          fontWeight: "bold",
          spacing: 6,
        },
      ],
    },
  ],
  title: {
    text: "Company Budget Allocation",
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

data.ts

export const data = [
  {
    name: "Engineering",
    children: [
      { name: "Frontend", budget: 320 },
      { name: "Backend", budget: 410 },
      { name: "Platform", budget: 180 },
    ],
  },
  {
    name: "Sales",
    children: [
      { name: "Enterprise", budget: 150 },
      { name: "SMB", budget: 90 },
    ],
  },
  { name: "Marketing", budget: 130 },
  { name: "Support", budget: 20 },
];

{
    series: [
        {
            type: 'sunburst',
            labelKey: 'name',
            sizeKey: 'budget',
            sizeName: 'Budget',
            innerRadiusRatio: 0.4,
            innerCircle: {
                fill: '#c9fdc9',
            },
            innerLabels: [
                {
                    text: 'Total Budget',
                    fontSize: 12,
                    color: 'gray',
                },
                {
                    text: '$1.3M',
                    fontSize: 24,
                    fontWeight: 'bold',
                    spacing: 6,
                },
            ],
        },
    ],
}

In this example:

An optional innerRadiusRatio is provided. This should be a value between 0 and 1 and defines the radius of the inner circle as a ratio of the outer radius of the series.
Use innerRadiusSize instead to set a fixed pixel radius.
The innerLabels property is used to add several lines of text into this space.
The colour of the centre area can be changed by using innerCircle.fill.

Highlighting Copy Link

main.ts

import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  SunburstSeriesModule,
} from "ag-charts-enterprise";
import { energyMix } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  LegendModule,
  SunburstSeriesModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data: energyMix,
  title: {
    text: "Sunburst Highlight States",
  },
  subtitle: {
    text: "Branch-sensitive styling",
  },
  series: [
    {
      type: "sunburst",
      labelKey: "name",
      sizeKey: "value",
      highlight: {
        highlightedItem: { stroke: "green" },
        highlightedBranch: { strokeWidth: 2 },
        unhighlightedItem: { opacity: 0.5 },
        unhighlightedBranch: { opacity: 0.1 },
      },
    },
  ],
};

options.container = document.getElementById("myChart");

const chart = AgCharts.create(options);

data.ts

export const energyMix = [
  {
    name: "Renewables",
    children: [
      { name: "Wind", value: 35 },
      { name: "Solar", value: 25 },
      { name: "Hydro", value: 20 },
    ],
  },
  {
    name: "Fossil Fuels",
    children: [
      { name: "Gas", value: 30 },
      { name: "Coal", value: 18 },
      { name: "Oil", value: 12 },
    ],
  },
];

Each sunburst highlight state exposes a separate style object.

highlightedItem – the hovered segment.
highlightedBranch – All segments that share the same root node.
unhighlightedItem – All segments in the highlightedBranch that are not the highlighted segment.
unhighlightedBranch – segments that belong to different branches.

{
    series: [
        {
            type: 'sunburst',
            labelKey: 'name',
            sizeKey: 'value',
            highlight: {
                highlightedItem: { stroke: 'green' },
                highlightedBranch: { strokeWidth: 2 },
                unhighlightedItem: { opacity: 0.5 },
                unhighlightedBranch: { opacity: 0.1 },
            },
        },
    ],
}

In this configuration:

Hovered segments get an accent stroke while preserving the default fill.
Sibling segments in the same branch inherit highlightedBranch styles (merged with their own highlight state).
Segments in other branches fade based on unhighlightedBranch.

Sunburst Chart Examples Copy Link

See more Sunburst Chart examples in the AG Charts Gallery.

Sunburst Chart Example

Sunburst Chart with Nesting Example

Sunburst Chart with Colour Range Example

API Reference Copy Link

Properties available on the AgSunburstSeriesOptions interface.

type required 'sunburst': Configuration for the Sunburst Series.
innerLabels AgSunburstInnerLabel[]: Configuration for the labels at the centre of the series. Has no effect unless `innerRadiusRatio` or `innerRadiusSize` is set.
id string default: auto-generated value: Primary identifier for the series. This is provided as `seriesId` in user callbacks to differentiate multiple series. Auto-generated ids are subject to future change without warning, if your callbacks need to vary behaviour by series please supply your own unique `id` value.
context ContextDefault: Context object to use in callbacks.
data DatumDefault[]: The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
visible boolean: Whether to display the series.
cursor string: The cursor to use for hovered markers. This config is identical to the CSS `cursor` property.
nodeClickRange InteractionRange: Range from a node that a click triggers the listener.
listeners AgSeriesListeners: A map of event names to event listeners.
labelKey string: The name of the node key containing the label.
secondaryLabelKey string: The name of the node key containing a secondary label.
childrenKey string: The name of the node key containing the children. Defaults to `children`.
sizeKey string: The name of the node key containing the size value.
colorKey string: The name of the node key containing the colour value. This value (along with `colorScale` config) will be used to determine the segment colour.
sizeName string: A human-readable description of the size values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
colorName string: A human-readable description of the colour values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
label AgChartAutoSizedLabelOptions: Options for the label in a sector.
secondaryLabel AgChartAutoSizedSecondaryLabelOptions: Options for a secondary, smaller label in a sector - displayed under the primary label.
cornerRadius PixelSize: Apply rounded corners to each sector.
innerRadiusRatio Ratio: The ratio of the inner radius of the series. Carves a hole at the centre of the series.
innerRadiusSize PixelSize: The size in pixels of the hole carved at the centre of the series, measured outwards from the centre. Must be greater than zero, and is added to any hole `innerRadiusRatio` carves. It is not capped: a value that reaches the series radius leaves the sectors no room, so nothing is rendered.
innerCircle AgSunburstInnerCircle: Configuration for the area at the centre of the series. Has no effect unless `innerRadiusRatio` or `innerRadiusSize` is set.
sectorSpacing PixelSize: Spacing between the sectors.
padding PixelSize: Minimum distance between text and the edges of the sectors.
fills AgColorType[]: The colours to cycle through for the fills of the sectors. An array of colour strings, or fill objects for gradients, patterns, or images.
strokes CssColor[]: The colours to cycle through for the strokes of the sectors.
fillOpacity Opacity: The opacity of the fill for the sectors.
strokeOpacity Opacity: The opacity of the stroke for the sectors.
strokeWidth PixelSize: The width in pixels of the stroke for the sectors.
colorScale AgColorScale: Configuration for colour scale with fills, domain, and mode.
tooltip AgSeriesTooltip: Series-specific tooltip configuration.
itemStyler Styler: A callback function for adjusting the styles of a particular Sunburst sector based on the input parameters.
highlight AgSunburstSeriesHighlightOptions: Highlight configuration for the series.
selection AgSelectionOptions: Configuration for data selection.

Getting started

AI Features

Core features

Specialised Charts

Series

Gauges

JavaScript ChartsSunburst Series

Simple Sunburst Copy Link

Sizing Copy Link

Colour Scale Copy Link

Other Colours Copy Link

Labels Copy Link

Inner Circle Copy Link

Highlighting Copy Link

Sunburst Chart Examples Copy Link

API Reference Copy Link