d3-org-chart

The OrgChart is primarily a single class. Its internal state is managed by an attrs object, where each property is overridable by the user.

Properties in attrs control various aspects of the chart, such as duration (which controls animation speed for expanding or collapsing nodes).

To interact with these properties, you can use getter/setter methods on the OrgChart instance. These methods are chainable.

You can quickly implement an org chart by including the required scripts (d3, d3-org-chart, and d3-flextree) and initializing the OrgChart class. This example loads data from a remote CSV file.

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

To use d3-org-chart in your project, install it using npm:

npm i d3-org-chart

Sample Data

Use the following CSV for testing and sample data implementation: data-oracle.csv

API and Method Reference

For a comprehensive overview of all exposed methods and their functionality, refer to the Futuristic Example, which demonstrates various button-bound functions and full library capabilities.

You can explore various visual styles and framework integrations for d3-org-chart via StackBlitz.

Visual Styles

• Default: Standard layout.
• Sky: Sky-themed design.
• Circles: Node shapes using circles.
• Oval: Node shapes using ovals.
• Clean: A minimalist design.
• Futuristic: A high-functionality, advanced design.
• Prev version design: Legacy design style.

Framework Integrations

• Vue.js Integration
• React integration
• Angular integration

The OrgChart API is designed to be chainable, allowing you to configure multiple properties in a single statement during initialization or at runtime.

During initialization:

const chart = new OrgChart()
                    .data(ourData)
                    .container(ourDomElementOrCssSelector)
                    .duration(ourDuration)
                    .render();

At runtime (e.g., updating data):

chart.data(updatedData).render();

const chart = new OrgChart()
                    .data(ourData)
                    .container(ourDomElementOrCssSelector)
                    .duration(ourDuration)
                    .render();

// You can also update data at runtime
chart.data(updatedData).render();

Import OrgChart from d3-org-chart and use the chainable API to configure the container, provide data, and render the chart.

import { OrgChart } from 'd3-org-chart';

 new OrgChart()
     .container(<DomElementOrCssSelector>)
     .data(<Data>)
     .render();

You can retrieve or update properties on an OrgChart instance using getter and setter methods. For example, to manage the animation duration:

Get value: Use chart.getChartState().duration or the shorthand chart.duration().

Set value: Pass the new value as an argument to the same method: chart.duration(3000).

// Assuming 'chart' is an instance of OrgChart

// Getting the value
chart.getChartState().duration
// OR
chart.duration()

// Setting the value
chart.duration(3000) // Sets animation duration to 3 seconds

The initialZoom(zoomLevel) method allows you to set a specific scale factor for the chart's zoom level. This is useful for controlling the starting magnification of the chart during the initial render or after specific state changes. It modifies the lastTransform.k property of the chart state.

// Set the zoom level to 1.5x
chart.initialZoom(1.5);

Use the removeNode(nodeId) method to remove a specific node and all of its descendants from the organization chart. The method searches the current hierarchy for the provided nodeId. If found, it marks the node and its descendants for removal, filters the underlying data, and triggers a redraw. If the removal results in an empty dataset, the chart will re-render as an empty state.

// Removing a node by its unique ID
chart.removeNode('employee-123');

To prevent memory leaks or unwanted behavior when a component is unmounted, use the clear() method. This removes all resize event listeners from the window and removes all elements from the SVG container.

chart.clear();

The chart requires a hierarchical dataset and configuration for identifying nodes and their parents:

• data(array): An array of objects representing the hierarchy. Each object must have a unique ID and a reference to its parent ID.
• nodeId(accessor): A function to retrieve the unique ID of a node. Default: d => d.nodeId || d.id.
• parentNodeId(accessor): A function to retrieve the parent's ID. Default: d => d.parentNodeId || d.parentId.

chart.data([
  { id: '1', parentId: null, name: 'Root' },
  { id: '2', parentId: '1', name: 'Child' }
]).nodeId(d => d.id).parentNodeId(d => d.parentId);