Hex UIv1

Sunburst

Radial hierarchy by value. Each ring is a deeper level of the tree; segment angles are proportional to summed values. Click a segment to drill in; click the center to zoom out.

Installation

pnpm
pnpm dlx @hex-core/cli add sunburst

Usage

tsx
import { Sunburst } from "@/components/ui/sunburst"

Two-level sunburst

Visualize a portfolio split with sub-allocations.

tsx
<Sunburst root={{
  id: "root", label: "Portfolio",
  children: [
    { id: "eq", label: "Equity", children: [
      { id: "us", label: "US", value: 60 },
      { id: "intl", label: "Intl", value: 20 },
    ]},
    { id: "fx", label: "Fixed Income", value: 20 },
  ],
}} />

Custom center label with totals

Use centerLabel to show the sum or other context.

tsx
<Sunburst centerLabel={<strong>$1.2M</strong>} root={portfolio} />

API Reference

PropTypeDefaultDescription
rootrequired
object—Hierarchy root: { id, label, value?, children? }. Leaves require a positive `value`; internal nodes are summed.
drillable
booleantrueWhen true, clicking a segment with children focuses it as the new center. Click the center to zoom back out.
centerLabel
ReactNode—Optional content rendered at the SVG center (e.g. a total). Falls back to the focused node's label.
size
number400Pixel size of the rendered SVG (it's square).
onSegmentClick
function—Called with the clicked SunburstNode. Fires before any internal drill.
className
string—Additional CSS classes on the SVG element.

AI Guidance

When to use

Visualize a value-scaled hierarchy where the user wants to see both the parent share and child sub-shares at once — portfolio allocations, time spent by category × subcategory, file system disk usage. Drill-down lets users focus a branch. `onSegmentClick` fires for ALL segments BEFORE the internal drill so consumers can observe pre-drill focus.

When not to use

Don't use for hierarchies without meaningful values per leaf (use MindMap or OrgChart). Don't use for >4 levels — outer rings become unreadable. Don't use for arbitrary node-edge graphs (use Canvas).

Common mistakes

  • Leaf values that don't sum at internal nodes — d3-hierarchy aggregates leaves; internal-node `value` props are ignored when children exist
  • Negative or zero leaf values — produce zero-width arcs or NaN angles. Filter or clamp upstream
  • Forgetting the resetting effect — when the parent updates `root` to a different tree, the focused id may no longer exist; the component re-syncs to the new root automatically

Accessibility

The SVG carries role="img" with a <title> and <desc> summarizing segment count and focused node. Drill-down is mouse-only by default; expose a parallel <table> or breadcrumb for keyboard / screen-reader users.

Token budget: 360

Verified against @hex-core/components@1.12.0

Edit this page on GitHub