Hierarchy Diagram

Hierarchy Diagram is a data-driven React component for rendering organizational charts, family trees, and other nested hierarchy diagrams without exposing internal list markup.

Installation

npm install hierarchy-diagram
# or
yarn add hierarchy-diagram
# or
pnpm add hierarchy-diagram

Peer dependencies:

• React 18+
• React DOM 18+

Demo

• GitHub Pages: https://drexxdk.github.io/hierarchy-diagram/
• Local demo: yarn dev

The GitHub Pages demo is a simple Vite React page that mirrors the current interactive example controls and hierarchy layout.

Why This API

• Consumers pass nested data instead of composing structural child components.
• Internal markup is package-owned, so global ul and li styles do not affect the diagram.
• Shared tree styling is controlled through line, card, and layout props.
• Per-node overrides stay explicit through className and card on each node.
• renderNode gives full control over node content without giving up the built-in tree layout.

Example

import HierarchyDiagram, { type HierarchyDiagramNode } from "hierarchy-diagram";

const data: HierarchyDiagramNode[] = [
  {
    label: "Emma Johnson",
    className: "bg-pink-500 text-white",
    children: [
      {
        label: "Noah Alexander Smith",
        children: [{ label: "Sophia Lee Martinez" }],
      },
    ],
  },
];

export function Example() {
  return (
    <HierarchyDiagram
      data={data}
      loading={<div>Loading hierarchy...</div>}
      line={{ color: "#d1d5db", width: 2, radius: 12 }}
      card={{ border: true, borderColor: "#e5e7eb", borderRadius: 12 }}
      layout={{ padding: 24, separator: 20 }}
      nodeClassName="bg-white text-slate-900"
      renderNode={({ node, path }) =>
        path === "root.0" ? <strong>{node.label}</strong> : node.label
      }
    />
  );
}

Compatibility

• Package runtime: React 18+
• Development environment: Node.js 20+
• Output format: ESM

Styling

• The package ships its own CSS module. There is no global stylesheet to import.
• Shared connector and card visuals are controlled through the line, card, and layout props.
• Per-node styling stays explicit through className and card on each node.
• Wide hierarchies naturally overflow horizontally. Wrap the component in a scroll container when your layout needs to support narrower viewports.

Accessibility notes

• The component renders package-owned div structure for layout stability and style isolation.
• It does not currently provide tree-specific keyboard navigation or ARIA tree semantics.
• If your product requires richer assistive technology support, supply accessible content inside renderNode and validate the result in your application context.

API

data

An array of nested HierarchyDiagramNode objects. Each node supports:

• id?: optional explicit React key
• label: node content
• children?: nested child nodes
• className?: per-node class override
• card?: per-node card style override

line

Controls connector appearance.

• color?
• width?
• radius?
• style?: solid | dashed | dotted

card

Controls the default node card appearance.

• border?
• borderColor?
• borderWidth?
• borderRadius?
• borderStyle?
• background?
• color?
• fontWeight?

layout

Controls diagram spacing.

• padding?
• separator?

loading

Optional placeholder content while the component resolves the device-pixel-optimized connector width on the client.

nodeClassName

Applies the same className to every rendered node card.

renderNode

Optional callback for replacing the default node content. The callback receives:

• node
• path
• depth
• hasChildren
• isRoot

validateData

Optional runtime validation for the incoming data structure.

Use validateData when:

• data comes from an API, CMS, or database response
• the package is consumed from plain JavaScript
• you want a clear early error when children is malformed

Skip validateData when:

• your data is already strongly typed in TypeScript
• you want the package to do no extra runtime checks

validateData only validates the recursive shape of the tree data. It does not sanitize or inspect rendered React content.

validate

Legacy alias for validateData. Prefer validateData in new code.

Wrapper div props

Standard HTMLAttributes<HTMLDivElement> such as className, style, id, role, and data-* attributes are passed through to the root wrapper.

Development

Run the demo:

yarn dev

Build the package:

yarn build

Build the GitHub Pages demo:

yarn build:demo

Run validation:

yarn lint
yarn test