Migrating to ApexTree 2.0
No public option or method was removed in 2.0. Every new option defaults to inert. The major version reflects changed defaults rather than a broken API: motion is on, the expand/collapse control is redesigned, and reading node positions synchronously after render() now returns a different answer.
Four changes are visible without opting in.
1. Node positions read synchronously after render()
A first render now seeds every node on the root and springs them outward. Reading data-x / data-y, or a foreignObject's x / y, immediately after render() returns the seed position, not the settled layout.
This already applied to expand() in earlier versions; the two paths are now consistent.
If you measure layout from the DOM, disable animation for that instance:
// positions are final synchronously
new ApexTree(el, { enableAnimation: false }).render(data)
Otherwise, wait for the springs to settle before measuring. This is the change most likely to affect an existing test suite.
2. The collapse count moved inside the button
A collapsed node's hidden-descendant count now renders inside the expand/collapse button, which widens into a pill. The separate badge element below the button is gone.
The collapseBadge* options and --apex-tree-badge-* CSS variables still work and now style that pill, with one added constraint: collapseBadgeFontSize is capped at 70% of the button size so a themed value cannot overflow it.
- If you targeted the badge's own element in CSS or in tests, retarget the button.
- If you compensated for the badge's extra 27.5px of vertical footprint in your spacing, remove that compensation. The old badge added footprint the layout never accounted for.
3. The expand/collapse button looks different
The old glyphs were annuli painted over the button's own bordered circle at the same diameter, so the icon ring and the border sat flush and read as one heavy rim. They are now plain stroked arms.
| What changed | 1.15 | 2.0 |
|---|---|---|
| Glyph | Annulus | Stroked arms |
expandCollapseButtonSize | hardcoded 14 | option, default 15 |
expandCollapseButtonBorderColor | '#BCBCBC' | '#E4E7EC' |
| Hover color | Hardcoded Bootstrap blue | borderColorHover |
| Radial button placement | Reused the 'top' case | Ray-rectangle intersection along the growth direction |
Pin the old look with:
const tree = new ApexTree(el, {
expandCollapseButtonSize: 14,
expandCollapseButtonBorderColor: '#BCBCBC',
})
There is no flag to restore the annulus glyph.
The radial placement change is a bug fix, but a visible one: radial previously parked every button at bottom centre, which was correct only near the bottom of the dial and sat on the incoming parent edge for nodes near the top.
Two related additions are opt-in: expandCollapseButtonIconColor (default '#475467') themes the glyph, which previously rendered black and disappeared on the dark theme's button, and expandCollapseButtonHaloColor (default '', off) draws an opaque ring so the button punches through the node border and the incoming edge.
4. Collapse and expand re-fit the camera with a zoom cap
1.15 fitted the viewBox tightly to whatever remained visible, so collapsing down to two nodes could balloon them to fill the canvas. maxZoomNodeSpan (default 8) now caps how far that fit zooms in.
new ApexTree(el, { maxZoomNodeSpan: 0 }) // old tight fit
new ApexTree(el, { enableExpandCollapseZoom: false }) // viewBox never moves
The cap never zooms out past the full tree and never shrinks the chart below 1:1, so a small chart keeps its tight fit instead of being scaled down on every collapse.
Turning the motion off entirely
enableAnimation: false renders and reflows with no motion, exactly as 1.15 did:
const tree = new ApexTree(el, { enableAnimation: false })
The tree also honours reduced motion. Add apextree-reduced-motion to the container, or wire it to matchMedia, and animations are skipped with elements shown at their final state. See Motion and Animation.
Summary
| Change | Restore 1.15 behavior |
|---|---|
| Motion on first render and reflow | enableAnimation: false |
| Collapse zoom cap | maxZoomNodeSpan: 0 |
| Button size and border | expandCollapseButtonSize: 14, expandCollapseButtonBorderColor: '#BCBCBC' |
| Collapse count inside the button | not configurable |
Every other addition is off or neutral by default and needs no attention on upgrade: motion, focus, semanticZoom, autoNodeHeight, cardExpansion, edgeFlow, layoutType, nodeWrapper, loadChildren, enableCommandPalette, the countBadge* family, and the radial direction.
What you get for the upgrade
The additive surface, each documented on its own page:
- Motion and Animation — the spring core, presets, stagger
- Radial and Dendrogram Layouts —
direction: 'radial',layoutType: 'cluster' - Node Sizing and Expandable Cards — per-node sizes,
autoNodeHeight, cards that expand in place - Focus Mode and the Active Path — spotlight a lineage, flow a path
- Semantic Zoom — level-of-detail node content
- Live Data Updates —
updateData()and time travel - Lazy Children — load subtrees on expand
- Command Palette —
Cmd/Ctrl + K
Framework wrappers
The wrappers track the core release:
| Wrapper | Version |
|---|---|
react-apextree | 2.1.0 |
vue-apextree | 2.1.0 |
ngx-apextree | 1.2.0 |
Each passes options straight through, so everything above applies unchanged. See React, Angular and Vue.