External Labels

External labels render a node's text as an SVG <text> element positioned outside the node box, instead of inside the node card. This enables marker-style trees: small circular nodes with their labels floating above, beside, or below, optionally rotated.

Enabling external labels

Set externalLabel.enabled: true. When enabled, the in-node nodeTemplate is suppressed and the label is drawn outside the node. The node box still renders (background, border, radius), so pair it with a small nodeWidth/nodeHeight and a rounded border for a marker look:

const tree = new ApexTree(document.getElementById('chart'), {
  nodeWidth: 16,
  nodeHeight: 16,
  borderRadius: '50%',       // circular marker
  nodeBGColor: '#6366F1',
  externalLabel: {
    enabled: true,
    verticalAlign: 'bottom',
    offsetY: 6,
  },
})
tree.render(data)

ExternalLabelOptions

Option	Type	Default	Description
enabled	boolean	false	Render the label outside the node bounds
align	'left' | 'center' | 'right'	'center'	Horizontal placement relative to the node
verticalAlign	'top' | 'middle' | 'bottom'	'middle'	Vertical placement relative to the node
offsetX	number	0	Extra horizontal offset applied after align
offsetY	number	0	Extra vertical offset applied after verticalAlign
rotation	number	0	Rotation in degrees around the label anchor
fontColor	string	inherits	Override the global fontColor for the label
fontFamily	string	inherits	Override the global fontFamily for the label
fontSize	string	inherits	Override the global fontSize for the label
fontWeight	string	inherits	Override the global fontWeight for the label

Alignment

align and verticalAlign position the label relative to the marker:

// label to the right of the marker, vertically centered
externalLabel: {
  enabled: true,
  align: 'right',
  verticalAlign: 'middle',
  offsetX: 8,
}

• align: 'left' anchors text to the right (label sits left of the node)
• align: 'right' anchors text to the left (label sits right of the node)
• verticalAlign: 'top' anchors text to the bottom (label sits above)
• verticalAlign: 'bottom' anchors text to the top (label sits below)

Rotated labels

Use rotation for vertical labels — common in inverted tree/timeline visualizations where many leaf labels would otherwise overlap:

const tree = new ApexTree(el, {
  direction: 'top',
  nodeWidth: 12,
  nodeHeight: 12,
  borderRadius: '50%',
  paddingY: 140,   // room for rotated labels below the leaves
  externalLabel: {
    enabled: true,
    verticalAlign: 'bottom',
    rotation: 90,    // reads top-to-bottom
    offsetY: 8,
  },
})
tree.render(data)

Use rotation: -90 for bottom-to-top text. Add paddingX/paddingY so rotated labels that extend past the marker bounds aren't clipped by the viewBox.

Per-node external labels

Each field can be set per-node via NestedNode.options.externalLabel, layered onto the global config. This lets most nodes use the default in-node card while specific nodes render a floating label:

const data = {
  id: 'root',
  name: 'Root',
  children: [
    {
      id: 'a',
      name: 'Leaf A',
      children: [],
      options: {
        externalLabel: { enabled: true, verticalAlign: 'bottom', rotation: 90 },
      },
    },
  ],
}

Styling the label independently

The fontColor/fontFamily/fontSize/fontWeight fields override the global font options for the external label only, so markers can have a different label style from in-node text:

externalLabel: {
  enabled: true,
  verticalAlign: 'bottom',
  fontColor: '#334155',
  fontSize: '13px',
  fontWeight: '600',
}

React example

import { ApexTreeChart } from 'react-apextree'

const options = {
  nodeWidth: 14,
  nodeHeight: 14,
  borderRadius: '50%',
  nodeBGColor: '#6366F1',
  paddingY: 120,
  externalLabel: {
    enabled: true,
    verticalAlign: 'bottom' as const,
    rotation: 90,
    offsetY: 8,
    fontSize: '12px',
  },
}

export default function MarkerTree() {
  return <ApexTreeChart data={data} options={options} />
}