d3-org-chart
Version:
Highly customizable org chart, created with d3
341 lines (247 loc) • 15.3 kB
Markdown
[](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md)
# Highly customizable d3 based organization chart
<span class="badge-npmversion"><a href="https://npmjs.org/package/d3-org-chart" title="View this project on NPM"><img src="https://img.shields.io/npm/v/d3-org-chart.svg" alt="NPM version" /></a></span>
[](https://npmjs.org/package/d3-org-chart)
<p align="center">
<!-- Thanks Vasturiano for this trick - https://github.com/vasturiano -->
<a href="https://stackblitz.com/edit/web-platform-o5t1ha"><img width="100%" src="https://user-images.githubusercontent.com/6873202/129306455-09f47e5e-0dc8-41b5-8fe2-da3fa4e0f7ed.gif"></a>
</p>
[Medium article about this project](https://bumbeishvili.medium.com/introducing-a-new-org-chart-130368314f04)
Highly customizable org chart built with d3 v7.
## Features
<table>
<tr>
<td>
<a href="https://stackblitz.com/edit/js-mfzkbs?file=index.html">
Simple Data <br/>
<img width=180 src="https://user-images.githubusercontent.com/6873202/209858323-9e135676-b95f-491f-897c-182f5d87ffae.png"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-yw1urt?file=index.html">
Custom Content <br/>
<img width=180 src="https://user-images.githubusercontent.com/6873202/209859788-0404aef9-793d-4f32-9209-bf1baec57a92.png"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-pwlmhf?file=index.html">
Nested Data <br/>
<img width=180 src="https://user-images.githubusercontent.com/6873202/209858323-9e135676-b95f-491f-897c-182f5d87ffae.png"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-36myfl?file=index.html">
Online Data <br/>
<img width=180 src="https://user-images.githubusercontent.com/6873202/209858323-9e135676-b95f-491f-897c-182f5d87ffae.png"/>
</a>
</td>
</tr>
<tr>
<td>
<a href="https://stackblitz.com/edit/js-dppjis?file=index.html">
CSV Data <br/>
<img width=180 src="https://user-images.githubusercontent.com/6873202/209864352-d0cbb5d7-0541-4239-86cc-428778a3bb35.png"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-rvwpza?file=index.html">
Styled Tree <br/>
<img width=180 src="https://user-images.githubusercontent.com/6873202/209865473-f9c3c846-5602-47a7-8cea-6a3eed3852c0.png"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-bexsmx?file=index.html">
Expand Node<img width=180 src="https://user-images.githubusercontent.com/6873202/209938311-74dcd25f-9fb2-4b30-a7cd-bd076f5762cc.gif"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-zkmxvd?file=index.html">
Collapse Node<img width=180 src="https://user-images.githubusercontent.com/6873202/209940922-f115f7f3-f5b3-4b79-b96a-9b8b7d2c1d34.gif"/>
</a>
</td>
</tr>
<tr>
<td>
<a href="https://stackblitz.com/edit/js-bb4p4k?file=index.html">
Add Node<img width=180 src="https://user-images.githubusercontent.com/6873202/209946403-61cc6808-7e2c-46a2-bf78-3206bbaac2fa.gif"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-qhrowa?file=index.html">
Remove Node<img width=180 src="https://user-images.githubusercontent.com/6873202/209946956-673679ba-8f59-4f59-b243-d78611e6650f.gif"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-q8n1mh?file=index.html">
Fit Screen<img width=180 src="https://user-images.githubusercontent.com/6873202/209947575-c75098b8-10f5-406d-afa8-de2fdd16bf76.gif"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-2ct1nt?file=index.html">
Change Layout<img width=180 src="https://user-images.githubusercontent.com/6873202/209948708-367b2802-c238-400c-a1ca-9908a6df549c.gif"/>
</a>
</td>
</tr>
<tr>
<td>
<a href="https://stackblitz.com/edit/js-rywzga?file=index.html">
Center Node<img width=180 src="https://user-images.githubusercontent.com/6873202/209949412-2e2b0084-5bb5-4eb5-9570-e5b83193b047.gif"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-rkjhzz?file=index.html">
Highlight Node<img width=180 src="https://user-images.githubusercontent.com/6873202/209951335-e77f996c-fe4f-4274-8b91-fe28a65b4231.gif"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-wrvy45?file=index.html">
Fullscreen<img width=180 src="https://user-images.githubusercontent.com/6873202/209955345-13040bed-f75e-4799-911e-f11bfa5f2164.gif"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-zd21e3?file=index.html">
Zoom in and out<img width=180 src="https://user-images.githubusercontent.com/6873202/209957228-6b6ce3fa-a336-4098-b8c3-91d53c93f4eb.gif"/>
</a>
</td>
</tr>
<tr>
<td>
<a href="https://stackblitz.com/edit/js-ue1cpj?file=index.html">
Export<img width=180 src="https://user-images.githubusercontent.com/6873202/209969502-6450648a-6a5c-460b-a23a-8c2ed0a81d2f.gif"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-nqzjts?file=index.html">
Expand & Collapse All<img width=180 src="https://user-images.githubusercontent.com/6873202/209975052-c79464fe-664e-4b61-9b3f-79776c883113.gif"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-tpbt7r?file=index.html">
Multi Node Connections<img width=180 src="https://user-images.githubusercontent.com/6873202/209976678-40db509e-98d7-40a4-8032-c30c60b724f3.gif"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-pr15gr?file=index.html">
Paging <img width=180 src="https://user-images.githubusercontent.com/6873202/209983512-1ecfc080-7570-430b-8770-feca5b6830fd.gif"/>
</a>
</td>
</tr>
<tr>
<td>
<a href="https://stackblitz.com/edit/js-sbp88f?file=index.html">
Horizontal View<img width=180 src="https://user-images.githubusercontent.com/6873202/209984126-c70565a5-f343-44fd-9006-7f74cd1dd3cd.gif"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-mc1rt4?file=index.html">
Active node centering<img width=180 src="https://user-images.githubusercontent.com/6873202/209985365-987fa6fb-523c-40be-8e6f-ddba856b7435.gif"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-fc2rrs?file=index.html">
Interactive Node<img width=180 src="https://user-images.githubusercontent.com/6873202/209988894-b294efbe-b021-4d5c-a7a5-7db4c8b22cd6.gif"/>
</a>
</td>
<td>
<a href="https://stackblitz.com/edit/js-wdexqc?file=index.html">
Searching org chart <img width=180 src="https://user-images.githubusercontent.com/6873202/268379088-9ddd5545-b2c8-46c5-a98e-377c456db885.gif"/>
</a>
</td>
</tr>
<tr>
<td>
<a href="https://stackblitz.com/edit/js-1kytuv?file=index.html">
Scrollable content <img width=180 src="https://user-images.githubusercontent.com/6873202/268471825-f1581769-21f3-419d-a32a-dbd2629ab2a0.gif"/>
</a>
</td>
</tr>
</table>
## How to use
Just copy this code and paste at - https://realtimehtml.com/
```html
<script src="https://d3js.org/d3.v7.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/d3-org-chart@3"></script>
<script src="https://cdn.jsdelivr.net/npm/d3-flextree@2.1.2/build/d3-flextree.js"></script>
<div class="chart-container"></div>
<script>
var chart;
d3
.csv(
"https://raw.githubusercontent.com/bumbeishvili/sample-data/main/org.csv"
)
.then((data) => {
chart = new d3.OrgChart().container(".chart-container").data(data).render();
});
</script>
```
### Installing
```
npm i d3-org-chart
```
```javascript
import { OrgChart } from 'd3-org-chart';
new OrgChart()
.container(<DomElementOrCssSelector>)
.data(<Data>) // https://github.com/bumbeishvili/sample-data/blob/main/data-oracle.csv
.render();
```
In general, we encourage to look into the source code to understand how it works. The chart code is basically a single class. At the top of the class, we have a state object called `attrs` which stores the state of the org chart and each single property is overridable by the user.
For example, one of the property name inside `attrs` object is `duration`, which controls animation duration for chart, when expanding or collapsing nodes.
If we want to get the value, we can either do
```javascript
chart.getChartState().duration
```
or directly
```javascript
chart.duration()
```
`chart` in the above case is an instance of `OrgChart` class. We can get it using `new OrgChart()`
If we want to set property, we can pass argument to the same function and it will automatically set the value
```javascript
chart.duration(3000) // This will become very slow moving chart
```
You can see list of all properties , their description of what each property does in the actual source code.
https://github.com/bumbeishvili/org-chart/blob/5be7e0962e46013b3a95dd19f41f829c3c853d1f/src/d3-org-chart.js#L41
Be aware that they are chainable, so if we wanted to set multiple properties, we would do this
```javascript
const chart = new OrgChart()
.data(ourData)
.container(ourDomElementOrCssSelector)
.duration(ourDuration)
.render()
// We can keep chaining values in runtime
chart.data(updatedData).render()
```
Have you impressively customized an organizational chart and want to be featured on this page? Just email me at me@davidb.dev and include screenshot of your org chart and it will be featured on this page (dimensions of image should be 500 X 500).
## Jump To Examples
| | |
| :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| <a href="https://stackblitz.com/edit/web-platform-sgsxzp"><img height="400px" src="https://user-images.githubusercontent.com/6873202/128979415-1b7fb969-6fc6-4a25-9ae2-87da7a9b031c.png"></a> <div style="100%">Default</div> | <a href="https://stackblitz.com/edit/web-platform-jyncb9"><img height="400px" src="https://user-images.githubusercontent.com/6873202/128979000-e5111571-8021-4c56-93d3-8d40dfe57536.png"></a> <div style="100%">Sky </div> |
| <a href="https://stackblitz.com/edit/web-platform-lwyild"><img height="400px" src="https://user-images.githubusercontent.com/6873202/128978399-32f890c6-86f7-46e2-b41e-58202e61f03b.png"></a> <div style="100%">Circles</div> | <a href="https://stackblitz.com/edit/web-platform-uhd3q7"><img height="400px" src="https://user-images.githubusercontent.com/6873202/129042576-0a8b27da-7a9d-4dee-b5b6-68080772cc9f.png"></a> <div style="100%">Oval</div> |
| <a href="https://stackblitz.com/edit/web-platform-3gwnsg"><img height="400px" src="https://user-images.githubusercontent.com/6873202/129054271-21ba5182-38c5-4856-bb21-727bba49243a.png"></a> <div style="100%">Clean (Design by [Anton](https://dribbble.com/shots/15480691-Org-chart))</div> | <a href="https://stackblitz.com/edit/web-platform-o5t1ha"><img height="400px" src="https://user-images.githubusercontent.com/6873202/129182014-610b6761-6dd4-4847-92cb-66407a900d03.png"></a> <div style="100%">Futuristic - Full Functionality</div> |
| <a href="https://stackblitz.com/edit/web-platform-thplyq"><img height="400px" src="https://user-images.githubusercontent.com/6873202/129419379-a9d055c8-723c-468f-bd87-4762ba721d87.png"></a> <div style="100%">Prev version design</div> |
#### Featured customizations:
Check out several libraries and frameworks integrations
- [Vue.js Integration](https://stackblitz.com/edit/d3-org-chart-vue-integration-su3d6r)
- [React integration](https://stackblitz.com/edit/d3-org-chart-react-integration-hooks)
- [Angular integration](https://stackblitz.com/edit/angular-ivy-gneris)
Custom components & algorithms I used
- [Curved edges - vertical](https://observablehq.com/@bumbeishvili/curved-edges-compacty-vertical)
- [Curved edges - horizontal](https://observablehq.com/@bumbeishvili/curved-edges-compact-horizontal)
- [Flextree Algorithm](https://github.com/Klortho/d3-flextree)
### Quick Docs
Check the sample data here - https://github.com/bumbeishvili/sample-data/blob/main/data-oracle.csv
For the full functionality of exposed methods check [Futuristic Example](https://stackblitz.com/edit/web-platform-o5t1ha) and button bound functions
For the high level overview of margins and content setting check the image bellow
## Notes & appreciations
I created this org-chart when I was hired by [TeamApps](https://github.com/teamapps-org).
Although this Org chart was specifically created for [teamapps java web application framework](https://github.com/teamapps-org/teamapps) , it's very flexible and can be used in any environment, where d3 and DOM is accessible.
Big thanks to [Matthias](https://github.com/Matthias-Bernstein) and [Yann](https://github.com/yamass), who assembled requirements for org-chart and had valuable pieces of advice afterwads.
Also, thanks all people who made generous [donations](https://ko-fi.com/bumbeishvili), it gives me motivation to further improve this org chart component.
Thanks [contractzen](https://www.contractzen.com/) for the significant contribution, which made implementation of some of the most important features (optimal layout, exporting ) possible.
## Author
[David B (twitter)](https://twitter.com/dbumbeishvili)
[David B (linkedin)](https://www.linkedin.com/in/bumbeishvili/)
I am available for freelance data visualization work. Please [contact me](https://davidb.dev/about) in case you'd like me to help you with my experience and expertise
You can also [book data viz related consultation session](https://www.fiverr.com/share/4XxG21) with me