Skip to content

OrigamChartSunburst ​

Hierarchical multi-level donut chart. Renders a recursive tree as concentric arc rings: each depth level becomes a ring, and each node occupies an angular sector proportional to its value within its parent's span.

Use cases: filesystem breakdowns, taxonomy hierarchies, budget allocation with sub-categories.

Import ​

ts
import { OrigamChartSunburst } from '@origam/ds'

Quick start ​

vue
<template>
  <origam-chart-sunburst
    :series="[{ name: 'Budget', data: budgetTree }]"
    :height="400"
    title="Budget Breakdown"
    subtitle="Q1 2026"
  />
</template>

<script setup lang="ts">
import { OrigamChartSunburst } from '@origam/ds'
import type { IChartSunburstDatum } from '@origam/ds'

const budgetTree: Array<IChartSunburstDatum> = [
  {
    name: 'Engineering', value: 50,
    children: [
      { name: 'Frontend', value: 20 },
      { name: 'Backend', value: 20 },
      { name: 'DevOps', value: 10 }
    ]
  },
  { name: 'Marketing', value: 30 },
  { name: 'Sales', value: 20 }
]
</script>

Props ​

Data ​

NameTypeDefaultDescription
seriesArray<IChartSeries>requiredReads series[0].data as Array<IChartSunburstDatum>. Extra series are ignored.

Visual ​

NameTypeDefaultDescription
titlestringundefinedOptional title above the chart.
subtitlestringundefinedOptional subtitle below the title.
heightnumber | string—Optional cap on the chart height (the chart is square: height = width, capped by this value). A plain number is px. Ignored when aspectRatio is set.
aspectRatiostringundefinedCSS aspect-ratio shorthand. Overrides height.
innerRadiusnumber0.15Proportion of the overall radius reserved for the centre hole. 0 = full pie. 0.4 = deep donut.
ringPaddingnumber1Radial gap in SVG pixels between consecutive depth rings.
colorSchemeArray<TIntent | string>8-intent cyclePalette applied to root nodes. Children inherit and lighten via color-mix.
showLabelbooleantrueRender arc name labels when angular span ≥ 0.1 rad.

Behaviour ​

NameTypeDefaultDescription
animatedbooleantrueFade arcs in on first paint. Respects prefers-reduced-motion.
animationDurationnumber600Animation duration in ms.
showLegendbooleantrueToggle the legend block (root nodes only).
legendPositionTChartLegendPosition'bottom'Legend anchor. One of 'top', 'bottom', 'left', 'right'.
showTooltipbooleantrueToggle the hover tooltip.

Formatting ​

NameTypeDefaultDescription
yAxisFormat(value: number) => stringString(value)Applied to values in tooltips and ARIA labels.

Emits ​

NamePayloadDescription
point-click(point: IChartPoint, event: MouseEvent | KeyboardEvent)Click or keyboard activation on an arc. point.x is the node name; point.y is the resolved value.
legend-click(series: IChartSeries, index: number)Click on a legend entry.
series-toggle(series: IChartSeries, visible: boolean)Resulting visibility flip after a legend click. Hiding a root hides its entire subtree.

Slots ​

NameBindingsDescription
tooltip{ point, series, category, node: IChartSunburstNode, path: string }Replace the default tooltip card. path is "Root > Branch > Leaf".
legend-item{ series: IChartSeries, index: number, visible: boolean }Replace one legend entry.
title—Replace the title + subtitle block.
empty—Rendered when series is empty or every root is hidden.

Data shape ​

ts
interface IChartSunburstDatum {
  name: string
  value?: number       // optional for internal nodes; computed from children if absent
  color?: TIntent | string
  children?: Array<IChartSunburstDatum>
}

Pass series[0].data as Array<IChartSunburstDatum>.

Behaviour notes ​

Responsive 1:1 drawing surface (#1324). The SVG viewBox is a square: its width follows the measured width of the container (useChartSize, a ResizeObserver) and its height equals that width, so the circle is never squashed. Text, strokes and markers keep their real pixel size instead of being scaled with a fixed canvas. height is now an optional cap: it has no default any more, and when set the side of the square is min(container width, available height). Until the box is measured (SSR, first paint) the 400 × 400 fallback is used, so hydration is unchanged.

Depth cap. A maximum of 4 depth levels are rendered. Nodes deeper than 4 are silently ignored.

Value inference. If an internal node omits value, it is computed as the sum of its children's resolved values recursively. Leaf nodes with no value contribute 0.

Colour lightening. Child arcs inherit the root colour lightened by depth × 15% via color-mix(in srgb, <parent> calc(100% - N%), white). Capped at depth 4 (60% lightening).

Legend. Shows root-level nodes only. Clicking a legend entry toggles the entire subtree.

Labels. Arc labels are only rendered when the angular span of the node is ≥ 0.1 rad (~5.7°). This prevents overlapping text on thin slices.

Empty state. When series is empty or every root is hidden, the #empty slot is rendered.

Accessibility. Each arc is a focusable <path> with role="button" and an aria-label in the form "Root > Branch: value". The chart is a single tab stop (roving tabindex, #1333): Tab enters it once, the arrow keys move between points, Tab leaves it — see the key table in the OrigamChart page. Arrow keys follow the DOM order: the order in which the arcs are rendered (the order of the computed layout), not the geometric neighbour. Enter or Space activates an arc. The SVG carries a <title> and <desc>.

Accessibility — the <desc> summary is localised AND agrees in number. The <desc> text is not an English literal: it resolves through the DS t() mechanism against origam.chart.sunburst.desc*, and the grammatical form is chosen by Intl.PluralRules for the ACTIVE locale — never by a count === 1 test in the component. A translator supplies only the forms their language needs (_one / _other cover en and fr; a Russian translation adds _few with no component change), and a category a locale does not define falls back to _other rather than leaking the raw key.

Animation. Arcs fade in on mount. Skipped when animated=false or prefers-reduced-motion: reduce.

Examples ​

Filesystem breakdown ​

vue
<template>
  <origam-chart-sunburst
    :series="[{ name: 'Filesystem', data: fsTree }]"
    :height="400"
    :inner-radius="0.2"
    title="Repository structure"
  />
</template>

<script setup lang="ts">
import { OrigamChartSunburst } from '@origam/ds'
import type { IChartSunburstDatum } from '@origam/ds'

const fsTree: Array<IChartSunburstDatum> = [
  {
    name: 'src', value: 1200,
    children: [
      { name: 'components', value: 500 },
      { name: 'composables', value: 300 },
      { name: 'utils', value: 200 },
      { name: 'types', value: 200 }
    ]
  },
  {
    name: 'tests', value: 400,
    children: [
      { name: 'unit', value: 250 },
      { name: 'e2e', value: 150 }
    ]
  },
  { name: 'docs', value: 100 }
]
</script>

Custom tooltip showing full path ​

vue
<template>
  <origam-chart-sunburst
    :series="[{ name: 'Budget', data: tree }]"
    :height="400"
  >
    <template #tooltip="{ path, point }">
      <div style="padding: 8px">
        <strong>{{ path }}</strong><br>
        {{ point?.y?.toLocaleString() }}
      </div>
    </template>
  </origam-chart-sunburst>
</template>