repository·master·Indexed 41 days ago
https://github.com/coreseekdev/react-org-chartA high-performance React component for rendering large-scale organizational charts using D3 and SVG. Version 0.1.1 supports lazy-loading and efficient rendering of collapsed nodes, capable of handling up to 1 million collapsed nodes and 5,000 expanded nodes.
react-org-chart is a high-performance organizational chart component built with D3-based SVG rendering. It is designed to handle large datasets, supporting up to 1 million collapsed nodes and 5,000 expanded nodes. It also supports lazy-loading children via a custom function.
When calling init(options), you can pass the following configuration properties to control the chart's appearance and behavior:
| Option | Description |
|---|---|
id | Required. The CSS selector for the DOM element that will host the chart. |
data | Required. The hierarchical tree data object. |
nodeWidth | The width of an individual node in pixels. |
nodeHeight | The height of an individual node in pixels. |
nodeSpacing | The spacing between nodes. |
lineType | The style of the connecting lines. Use 'angle' or other types (affects lineDepthY calculation). |
margin | An object containing top, left, right, and bottom margins. |
shouldResize | Boolean. If true, adds a global resize listener to adjust the SVG dimensions when the container changes size. |
treeData | Internal mapping for the data property. |
The react-org-chart component accepts a configuration object to customize the visual style, node dimensions, spacing, and animation behavior. You can control the following properties:
nodeWidth: Width of the individual nodes.nodeHeight: Height of the individual nodes.nodeSpacing: Spacing between nodes.nodePaddingX: Horizontal padding inside the node.nodePaddingY: Vertical padding inside the node.nodeBorderRadius: Corner radius for the node container.avatarWidth: Width of the avatar image within the node.margin: An object defining { top, right, bottom, left } margins for the chart area.shouldResize: Boolean indicating if the chart should resize with its container.lineType: The style of the connecting lines (e.g., 'angle').lineDepthY: The vertical depth of the line used for child nodes (typically matches node height).animationDuration: Duration of animations in milliseconds.backgroundColor: Background color of the chart.borderColor: Color of the node borders.nameColor: Color of the person's name.titleColor: Color of the person's job title.reportsColor: Color used for reporting relationship lines or text.const config = {
margin: { top: 20, right: 20, bottom: 20, left: 20 },
animationDuration: 350,
nodeWidth: 240,
nodeHeight: 120,
nodeSpacing: 12,
nodePaddingX: 16,
nodePaddingY: 16,
nodeBorderRadius: 4,
avatarWidth: 40,
lineType: 'angle',
lineDepthY: 120,
backgroundColor: '#fff',
borderColor: '#e6e8e9',
nameColor: '#222d38',
titleColor: '#617080',
reportsColor: '#92A0AD',
shouldResize: true
};The react-org-chart component accepts several props to control the data structure, dimensions, and visual style of the chart.
| property | type | description |
|---|---|---|
tree | Object | Required. Nested data model containing all employees. |
nodeWidth | Number | Width of the component for each individual. |
nodeHeight | Number | Height of the component for each individual. |
nodeSpacing | Number | Spacing between each of the nodes in the chart. |
animationDuration | Number | Duration of the animations in milliseconds. |
lineType | String | Type of line connecting nodes. Options: "angle" or "curve". |
// Example tree data structure
{
"id": 123,
"person": { "name": "Fouad Matin" },
"children": []
}The onClick handler manages node interactions, including custom click logic, lazy-loading of children, and expanding/collapsing nodes. You can customize this behavior by passing a configuration object to the onClick factory function.
| Option | Type | Description |
|---|---|---|
onPersonClick | function | A callback function invoked when a node is clicked. It receives (datum, d3.event). If this function returns false, the default expand/collapse or lazy-loading logic is cancelled. |
loadChildren | function | A callback used for lazy-loading. If a node has hasChild: true but no existing children or _children, this function is called with the datum. It can be synchronous or return a Promise. |
render | function | The function responsible for re-rendering the chart. It is called after state changes (like expanding/collapsing or loading children). |
tree | object | The D3 tree instance, required when using loadChildren to manipulate the node hierarchy. |
To enable lazy loading, your data nodes must include a hasChild: true property. When clicked, the chart will attempt to call loadChildren(datum).
const onClick = require('react-org-chart/src/chart/on-click');
const clickHandler = onClick({
onPersonClick: (datum, event) => {
console.log('Clicked:', datum);
// Return false to prevent default expand/collapse behavior
// return false;
},
loadChildren: async (datum) => {
const children = await fetch(`/api/employees/${datum.id}`);
return children;
},
render: (config) => {
// Trigger chart re-render
myChart.render(config);
},
tree: d3TreeInstance
});
// Usage in your D3/React render loop:
// node.on('click', clickHandler);The init function is the primary entry point for setting up the organization chart. It merges user-provided options with a default configuration, initializes a D3 tree layout, sets up SVG elements, and performs the initial render.
To use init, you must provide an id that matches a DOM element in your document where the SVG will be injected. You must also provide the data property (which is mapped to treeData internally).
const { init } = require('react-org-chart/src/chart');
const options = {
id: '#my-chart-container',
data: {
name: 'Root',
children: [
{ name: 'Child 1' },
{ name: 'Child 2' }
]
},
nodeWidth: 200,
nodeHeight: 50,
nodeSpacing: 20,
margin: { top: 20, left: 20, right: 20, bottom: 20 },
lineType: 'angle' // or 'straight'
};
init(options);The OrgChart component is a React wrapper for the underlying chart engine. It renders a container div and initializes the chart instance when the component mounts.
To use it, provide an id (which defaults to 'react-org-chart') and a tree prop containing your organizational data. Any additional props passed to the OrgChart component are forwarded directly to the init function of the core chart engine as configuration options.
const OrgChart = require('@latticehr/react-org-chart');
// Example usage:
<OrgChart
id="my-org-chart"
tree={yourTreeData}
// ...other chart options
/>The OrgChart component accepts the following props:
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | 'react-org-chart' | The HTML id assigned to the container div. Used as a CSS selector for initialization. |
tree | object | Required | The hierarchical data structure representing the organization. |
...options | object | N/A | Any other props passed to OrgChart are spread into the init function as configuration options for the chart engine. |
The package provides an init function attached to the OrgChart export. This function is used to perform initialization logic for the chart instance.
const OrgChart = require('@latticehr/react-org-chart');
// Initialize the chart
OrgChart.init();The main entrypoint of the package exports the OrgChart component. This component is intended to be used within a React application to render an organizational chart based on provided data and configuration.
const OrgChart = require('@latticehr/react-org-chart');
// Use OrgChart within your React component tree
function MyComponent() {
return <OrgChart {...props} />;
}