@antv/hierarchy

Layout algorithms for visualizing hierarchical data.

Features

✨ TypeScript Support: Fully typed with TypeScript for better IDE support and type safety

🚀 Modern Build System: Built with Vite for faster builds and smaller bundle sizes

📦 Multiple Formats: Supports both ES modules and UMD formats

🎯 Tree-shakeable: ES module format allows for efficient tree-shaking

Installation

npm install @antv/hierarchy

Usage

ES Module (Recommended)

import { compactBox } from '@antv/hierarchy';
// or
import * as Hierarchy from '@antv/hierarchy';

CommonJS

const Hierarchy = require('@antv/hierarchy');

TypeScript

This library includes TypeScript definitions. You'll get full IntelliSense support:

import { compactBox, type HierarchyNode, type CompactBoxOptions } from '@antv/hierarchy';

const options: CompactBoxOptions = {
  direction: 'LR',
  getId: (d) => d.id,
  getWidth: (d) => 100,
  getHeight: (d) => 50
};

API

example

import { compactBox } from '@antv/hierarchy';
// or for CommonJS
// const { compactBox } = require('@antv/hierarchy');

// your tree data
const root = {
  isRoot: true,
  id: 'Root',
  children: [
    {
      id: 'SubTreeNode1',
      children: [
        {
          id: 'SubTreeNode1.1'
        },
        {
          id: 'SubTreeNode1.2'
        }
      ]
    },
    {
      id: 'SubTreeNode2'
    }
  ]
};

// apply layout
const NODE_SIZE = 16;
const PEM = 5;
const ctx = document.getElementById('id-of-canvas-element').getContext('2d');
const rootNode = compactBox(root, {
  direction: 'H', // H / V / LR / RL / TB / BT
  getId(d) {
    return d.id;
  },
  getHeight(d) {
    if (d.isRoot) {
      return NODE_SIZE * 2;
    }
    return NODE_SIZE;
  },
  getWidth(d) {
    if (d.isRoot) {
      return ctx.measureText(d.id).width * 2 + PEM * 1.6;
    }
    return ctx.measureText(d.id).width + PEM * 1.6;
  },
  getHGap(d) {
    if (d.isRoot) {
      return PEM * 2;
    }
    return PEM;
  },
  getVGap(d) {
    if (d.isRoot) {
      return PEM * 2;
    }
    return PEM;
  },
  getSubTreeSep(d) {
    if (!d.children || !d.children.length) {
      return 0;
    }
    return PEM;
  }
});

layout types

Hierarchy[type]

compactBox

this layout differs from d3-hierarcy.tree, it is a compact box tidy layout that is tidy in both horizontal and vertical directions.

demos

LR	RL	H

TB	BT	V

dendrogram

demos

LR	RL	H

TB	BT	V

indented

demos

LR	RL	H

mindmap

this layout is inspired by XMind.

demos

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

• Full TypeScript support with comprehensive type definitions
• Modern build system using Vite
• ES module format support
• Type declaration files (.d.ts) for better IDE support
• TypeScript examples in README

Changed

• BREAKING: Package now uses ES modules by default (set "type": "module")
• Migrated entire codebase from JavaScript to TypeScript
• Replaced Webpack with Vite for faster builds
• Replaced Babel with native TypeScript compiler
• Updated build output structure:
  • dist/hierarchy.es.js - ES module format
  • dist/hierarchy.umd.js - UMD format
  • lib/*.d.ts - TypeScript declarations
• Improved package.json exports for better module resolution
• Updated README with TypeScript usage examples

Removed

• Webpack build system and configuration
• Babel transpilation
• ESLint configuration (to be replaced with modern linting later)
• UglifyJS (replaced with Vite's built-in Terser)
• 664 obsolete npm packages from dependencies

Performance

• Reduced bundle size: 9.88 kB (ES) / 10.19 kB (UMD)
• Gzipped size: ~3.8 kB
• Faster build times with Vite
• Tree-shakeable ES module exports

Developer Experience

• Full IntelliSense support in TypeScript and JavaScript projects
• Better error detection at compile time
• Source maps included for easier debugging
• Cleaner dependency tree (15 dev dependencies vs 24 previously)

[0.6.14] - Previous versions

See git history for previous changes.