@jack-pairce/react-org-chart-editor

Interactive, editable organization chart component for React. Build, visualize, and edit hierarchical role structures with drag-and-drop, connectors, and an unassigned users list.

Written in TypeScript
Ships ESM/CJS typings from dist
UI built with antd and tailwind (peer styles not required to consume the component)

Install

npm: npm i @jack-pairce/react-org-chart-editor antd
pnpm: pnpm add @jack-pairce/react-org-chart-editor antd
yarn: yarn add @jack-pairce/react-org-chart-editor antd

React 18+ is required.

What you get

The package exports a single component:

HierarchyPage — a fully featured org chart editor wrapped in internal context state.

Import path:

ESM: import { HierarchyPage } from '@jack-pairce/react-org-chart-editor'

The build exposes types in dist/index.d.ts.

Quick start

import { useState } from 'react';
import { HierarchyPage } from '@jack-pairce/react-org-chart-editor';
import type { Role, User } from '@jack-pairce/react-org-chart-editor/dist/types';

const initialRoles: Role[] = [
  { id: 1, name: 'CEO', color: '#4F46E5', parent_id: null, is_responsable: true, can_sudo: true, users_limit: 1, users: [], level: 0, children: [] },
];

const initialUsers: User[] = [
  { id: 100, name: 'Alice', role_id: null },
  { id: 101, name: 'Bob', role_id: 1 },
];

export default function Demo() {
  const [roles, setRoles] = useState(initialRoles);
  const [users, setUsers] = useState(initialUsers);

  return (
    <HierarchyPage
      headerTitle="Company Structure"
      roles={roles}
      users={users}
      isLoading={false}
      initialEditMode="none"
      onChange={({ roles: nextRoles, users: nextUsers }) => {
        setRoles(nextRoles);
        setUsers(nextUsers);
      }}
      onSave={async ({ added, updated, deleted, usersChanged }) => {
        // Persist to your backend
        console.log({ added, updated, deleted, usersChanged });
      }}
    />
  );
}

Props

HierarchyPage props are defined by HierarchyProps:

headerTitle: string — Title displayed in the header toolbar.
roles: Role[] — Flat list of roles. The component builds a tree internally (via parent_id).
users: User[] — All users. Users with role_id === null appear in the Unassigned list.
isLoading: boolean — Show a loading state.
initialEditMode?: 'none' | 'reorder' | 'content' — Optional starting mode.
onChange?: (next: { roles: Role[]; users: User[] }) => void — Fires whenever local state changes.
onSave?: (payload: { added: Role[]; updated: Role[]; deleted: Role[]; usersChanged: User[] }) => Promise | void — Called by UI save actions.

Types are available from the package types export, see below.

Types

Minimal, framework-independent types are included:

User (alias of DefaultUser)
- id: number
- name: string
- family?: string
- role_id: number | null
Role
- id: number
- name: string
- color: string
- parent_id: number | null
- is_responsable: boolean
- can_sudo: boolean
- users_limit: number
- users: { id: number; name: string; icon?: string | ReactNode | (() => ReactNode) }[]
- level: number
- children: Role[]
- Optional layout/runtime: x, y, isDragging, _new, _placeholder, _overlayed
EditMode: 'none' | 'reorder' | 'content'

Note: The component computes layout coordinates (x,y) and connector paths internally. Provide roles as a flat array; the tree is built from parent_id relationships.

Behavior overview

Tree building and layout: roles are converted to a tree, levels are measured, and SVG connectors are rendered between parents and children.
Drag-and-drop: move roles, reorder, and adjust levels. Height per level is computed dynamically.
Unassigned users: fixed list for users with role_id = null; drag onto roles.
Modes: editMode toggles behavior (reorder/content) while 'none' disables editing.
onChange/onSave: wire these to persist changes.

Styling

The component includes minimal internal styles (src/components/style.css) and uses antd components. Consumers can override styles via global CSS. Tailwind is used in development but not required in your app.

Development

Dev preview: pnpm dev
Build library: pnpm build (emits dist with types and JS)
Bundle single entry via tsup: pnpm bundle

Importing types

You can import types from the package root when using TypeScript:

import type { Role, User, EditMode } from '@jack-pairce/react-org-chart-editor/dist/types';

Alternatively, rely on inference by passing plain objects that match these shapes.

JSPM