# @antv/hierarchy

> layout algorithms for visualizing hierarchical data

Latest version **0.7.1** (published 2025-12-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install @antv/hierarchy
pnpm add @antv/hierarchy
yarn add @antv/hierarchy
bun add @antv/hierarchy
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.7.1 |
| Published | 2025-12-25 |
| First published | 2018-04-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 141.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 300 |
| Author | https://github.com/orgs/antvis/people |
| Maintainers | lvisei, freestyle21, soundquiet, elaine.q.10, sturuby, sakuya223, serializedowen, xdzhao, yangzhanmei, wjgogogo, leungwensen, dori, iaaron, yard, simaq, dxq613, intchous, susan_ann, jinke.li, lzxue, army8735, atool, baizn, dengfuping, neoddish, jeffy2012, zqlu, afc163, pomelo-nwu, kopiluwaky, ccnuzindex, panyuqi, bubkoo, zengyue, kasmine, boyu.zlj, l1ud0ngq1, newbyvector, winniexing, chenluli, kn9117, xdddst, semious2020, esora, nadia_liu, bbsqq, mxz96102, openwayne, pearmini, pddpd, yiqianyao, zhanba, cxxxxxn, laixingui.lxg, susiwen8, yanxiong, zeyuwang, rainy25ghz, zhangjunjie-loki, flash1, yisi.wang, dreammy23, biupiubiupiu, basketduck, xuying1027, banxuan, bqxbqxbqx, alex_zjt, duxinyue023, wang1212, leondt1, gaofuhong |
| Keywords | antv, hierarchy |

## Links

- npm: https://www.npmjs.com/package/@antv/hierarchy
- Repository: https://github.com/antvis/hierarchy
- Issues: https://github.com/antvis/hierarchy/issues
- npm.io page: https://npm.io/package/@antv/hierarchy

## Alternatives

- [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads
- [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads
- [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads
- [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads
- [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads

## Recent versions

- 0.7.1 (latest) — 2025-12-25
- 0.1.0-beta.4 (beta) — 2018-04-17
- 0.7.0 — 2025-12-12
- 0.6.14 — 2024-09-20
- 0.6.13 — 2024-08-29
- 0.6.12 — 2024-05-13
- 0.6.11 — 2023-02-21
- 0.6.10 — 2023-01-19
- 0.6.9 — 2023-01-19
- 0.6.8 — 2021-08-11
- 0.6.7 — 2021-03-22
- 0.6.6 — 2020-08-24
- 0.6.5 — 2020-08-17
- 0.6.4 — 2020-06-16
- 0.6.3 — 2020-04-08
- … 29 more at https://npm.io/package/@antv/hierarchy/versions

## README

<h1 align="center">
<b>@antv/hierarchy</b>
</h1>

> Layout algorithms for visualizing hierarchical data.

[![Build Status](https://github.com/antvis/hierarchy/actions/workflows/build.yml/badge.svg)](https://github.com/antvis/hierarchy/actions)
[![npm Version](https://img.shields.io/npm/v/@antv/hierarchy.svg)](https://www.npmjs.com/package/@antv/hierarchy)
[![npm Download](https://img.shields.io/npm/dm/@antv/hierarchy.svg)](https://www.npmjs.com/package/@antv/hierarchy)
[![npm License](https://img.shields.io/npm/l/@antv/hierarchy.svg)](https://www.npmjs.com/package/@antv/hierarchy)

## 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

```bash
npm install @antv/hierarchy
```

## Usage

### ES Module (Recommended)

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

### CommonJS

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

### TypeScript

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

```typescript
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

```typescript
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 |
| -------- | -------- | -------- |
| ![LR](./assets/compact-box-lr.png) | ![RL](./assets/compact-box-rl.png) | ![H](./assets/compact-box-h.png) |

| TB | BT | V |
| -------- | -------- | -------- |
| ![TB](./assets/compact-box-tb.png) | ![BT](./assets/compact-box-bt.png) | ![V](./assets/compact-box-v.png) |

#### dendrogram

> demos

| LR | RL | H |
| -------- | -------- | -------- |
| ![LR](./assets/dendrogram-lr.png) | ![RL](./assets/dendrogram-rl.png) | ![H](./assets/dendrogram-h.png) |

| TB | BT | V |
| -------- | -------- | -------- |
| ![TB](./assets/dendrogram-tb.png) | ![BT](./assets/dendrogram-bt.png) | ![V](./assets/dendrogram-v.png) |

#### indented

> demos

| LR | RL | H |
| -------- | -------- | -------- |
| ![LR](./assets/indented-lr.png) | ![RL](./assets/indented-rl.png) | ![H](./assets/indented-h.png) |

#### mindmap

this layout is inspired by XMind. 

> demos

![mindmap](./assets/mindmap.png)

---
_Source: https://npm.io/package/@antv/hierarchy · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._