Skip to content

Hierarchical Bar

A hierarchical bar chart is what you reach for when your data is not a flat list but a tree — a whole that breaks into parts, and those parts break down further. A portfolio splits into asset classes, and each class into holdings. A budget splits into departments, and each department into line items. An org splits into teams. The question is no longer just “how much?” but “how much, and what is it made of?”

HierarchicalBar answers that as an outline: one row per node, each with its own bar on a shared scale from one zero line. Parent rows carry their subtotal; nested rows read underneath them. You get the top-line comparison and the composition in a single figure, top to bottom, without a legend and without asking the reader to decode nested rectangles.

This is the linear view of a shallow hierarchy. For the spatial views of a deep one — treemap, pack, sunburst — that is a different tool. Bars are for reading a breakdown as a ranked, labeled list.

Data format

HierarchicalBar takes a tree, not an array of rows. A node is:

{
    label: 'World Liberty Financial',
    value: 536.4,
    children: [
        { label: 'Ethereum Key', value: 106 },
        { label: 'USDC Key',     value: 56 },
    ]
}

Pass one root object, or an array of roots (a forest — several top-level items with no shared total). Only label is required. children marks an internal node; color and remainderLabel are optional.

The same tree feeds the drill-down Donut — one data shape, two representations. Build the object once and hand it to whichever view fits the page.

Value is authoritative — and the remainder is real

A parent’s value is taken as stated. It may be larger than the sum of its listed children, and that difference is not an error to be normalized away — it is a genuine remainder: the undisclosed, the “other”, the part that was never itemized. In the portfolio above, World Liberty Financial is stated at $536.4M but its named holdings add up to $243.2M; the $293.2M gap is drawn as its own muted segment labeled Other token & equity sales.

The remainder is never surfaced silently. It appears only when you ask for it:

  • set remainderLabel on a node to surface that node’s remainder with a specific label, or
  • pass showRemainder: true to the chart to surface every node’s remainder using a fallback label.

If a parent’s children exceed its stated value, the data is inconsistent — the chart warns in the console and leaves the (negative) remainder undrawn, or throws instead when you pass strict: true.

Undisclosed items

Real breakdowns have holes: a line item you know exists but whose amount was never published. Give it value: null and it is kept as a placeholder — drawn with a ? marker, excluded from every sum, and left out of the parent’s remainder (an unknown can’t be subtracted). It is not the same as omitting the item, and not the same as a remainder: the remainder is a quantified gap, a null is a named but unquantified item. A parent with no value of its own whose children are all null is unquantified too: it gets the ? and stays out of the sums, rather than reading as zero.

{ label: 'License agreement with NFT INT, LLC', value: null }
// → drawn as “?”, counted in nothing

A leaf with no usable value at all — absent, zero, or negative — is simply dropped, since a compositional bar can only draw a positive magnitude.

Root, depth, and color

By default the root row is drawn as a neutral full-width total, and each top-level branch takes the next color from the theme palette. Descendants inherit their branch’s hue and fade one step per level, so nesting reads as shade without a second encoding. A node’s own color wins, except on the root row, which stays neutral, and on a remainder, which stays muted.

Set showRoot: false to drop a single root (an object, or an array of one) entirely and start from its children — the root then reads as the chart title/total rather than a bar. Use maxDepth to cap how deep the outline expands: 0 draws the top rows only, 1 adds their children. Indentation is indent px per level, applied to the name; row height is rowHeight.

Labels and values

On a plot at least 480 px wide, each row reads left to right: the name in a column of its own, flush against its bar (or, with labelAlign: 'left', indented by depth); the bar, starting from one zero line shared by every row, so lengths compare directly at any depth; and the value in a right-aligned column at the right edge. The name column is as wide as the longest name needs, up to 40% of the width. A longer name wraps once, at a word, and its row grows by a line; what the second line cannot hold ends in an ellipsis. Parent rows set their name and value in semibold, and a little space opens before each new branch group, so the nesting reads without relying on color.

On a narrower plot — a phone — the name sits on its own line above its bar, indented by depth and shortened with an ellipsis to the width, and the value follows the bar end, flipping inside the bar when space is tight.

In both layouts the tooltip keeps the full name; labelMaxLength cuts names to a fixed number of characters instead. Format the values with valueFormat: (node, info) => string, or turn them off with showValues: false.

Hovering a row shows its label, its value and its share of the total — the root’s value, also when showRoot: false hides its row; for a forest, the sum of the roots.

Quick example

new RareCharts.HierarchicalBar('#chart', {
  valueFormat: n => '$' + n.value + 'M',
  showRoot: false,       // root becomes the header, not a bar
}).setData({
  label: 'Portfolio', value: 100,
  children: [
    { label: 'Equities', value: 60, remainderLabel: 'Other', children: [
      { label: 'US Large Cap', value: 35 },
      { label: 'International', value: 18 },
    ] },
    { label: 'Bonds', value: 30 },
    { label: 'Cash',  value: null },   // undisclosed → “?”
  ],
});

Hierarchical Bar options

Common options shared by all chart types (title, subtitle, source, note, controls, theme) are documented on the Settings page. The legend is a caption here: the chart has no series to hide.

Option Type Default Description
Layout
rowHeight number 28 / 44 Height in px of a row: 28 when name, bar and value sit side by side, 44 when the name sits above the bar (a plot under 480 px). A name wrapped to two lines adds a line to its row. Chart height is content-driven — the rows, the space before each branch group, plus the top and bottom margin — so the common height option does not apply; width is always 100% of the container.
margin object {8, 8, 8, 0} Inner padding {top, right, bottom, left}; top and bottom add to the content height.
indent number 16 Horizontal indent in px per depth level, applied to the name when it is indented (stacked, or side by side with labelAlign: 'left'). Bars always start at the shared zero line.
labelAlign string 'right' Side by side: 'right' sets every name flush against the bars; 'left' lines the names up at the left edge, indented by depth. Stacked, the name is always indented.
barWidth number auto (16) Bar thickness in px, the name Bar and DualAxes use. By default the value-label font size + 2 — 16px with the standard 14px labels (--rc-font-size-sm). Before 0.9.8_7 it was barHeight, which no longer works.
showRoot boolean true Draw the root row(s). When false, a single root is dropped and its children become the top rows — the root reads as the header/total instead of a bar. No effect on a forest of two or more roots; a one-element array counts as a single root.
maxDepth number — Deepest level to render, 0-based from the top row: 0 draws the top rows only, 1 adds their children. Default: no limit.
Composition
remainderLabel string 'Other' Per-node (in the data) it labels and surfaces that node’s remainder. As a chart option it is the fallback label used when showRemainder is on.
showRemainder boolean false Surface every node’s remainder as a muted segment, using each node’s own remainderLabel or the fallback above.
strict boolean false Throw when a node’s children exceed its stated value. Off by default: the chart warns and leaves the negative remainder undrawn.
Value labels
showValues boolean true Print the values: in a right-aligned column when name, bar and value sit side by side; at the bar end when the name sits above the bar, flipping inside the bar when space is tight.
valueFormat function — (node, info) => string. Default: the value with thousands separators, decimals kept (d3.format(','): 1,400 · 536.4). Note the first argument is the node, so you can read node.value, node.label, node.depth; the second, info, is { label, value, color, percent } — the bar’s colour and the share of the total (null without a value).
missingGlyph string '?' Marker drawn where a value: null node’s bar would be.
labelMaxLength number — Truncate a label to N characters and add an ellipsis. The full label stays in the tooltip. Without it, a name longer than its room wraps (side by side) or shortens to the width (above the bar) on its own.
Animation
animate boolean true Grow bars from zero on first render and after every setData.
duration number 650 Animation duration in ms.
ease string 'cubicOut' Easing: 'cubicOut', 'cubicInOut', 'linear'.
Interaction
tooltipFormat function — (node, info) => html, info as for valueFormat (formatter arguments). Default shows the label, the value (or “not disclosed”), and its share of the total: the root’s value, shown or not, or the sum of a forest’s roots.