JavaScript ChartsOrg Chart

An Organisation Chart displays hierarchical relationships between people, departments, or entities as a tree of connected cards.

Simple Organisation Chart Copy Link

The Org Chart is designed to display a single series and is created using the organization series type.

The data passed in should be an array of nodes, with each node containing a unique identifier field, and a second field that references the identifier of its parent node. The root node should have a null value for its parentId.

{
    series: [
        {
            type: 'organization',
            idKey: 'id',
            parentIdKey: 'parentId',
            node: {
                title: { key: 'name' },
                subtitle: { key: 'job' },
                image: { key: 'avatar' },
                labels: [{ key: 'location' }],
            },
        },
    ],
}

In this configuration:

• idKey and parentIdKey define parent-child relationships. These default to 'id' and 'parentId' respectively.
• title and subtitle display the primary and secondary card text with the values from the provided data fields. The keys default to 'title' and 'subtitle' respectively.
• image displays an image sourced from the data field specified by key. The key defaults to 'image'.
• labels allow adding additional text rows below the subtitle, each mapping a data field via key.

Text Copy Link

Each node can display a title, subtitle as well as an array of labels.

{
    series: [
        {
            type: 'organization',
            node: {
                image: { key: 'avatar', position: 'left', height: 50, width: 50 },
                title: { key: 'name', textAlign: 'left', fontSize: 16 },
                subtitle: { key: 'job', textAlign: 'left', fontStyle: 'italic' },
                labels: [
                    { key: 'location', textAlign: 'left' },
                    {
                        key: 'status',
                        textAlign: 'right',
                        itemStyler: ({ datum }) => ({
                            fill: datum.status === 'Remote' ? '#fff3e0' : '#e8f5e9',
                            stroke: datum.status === 'Remote' ? '#ff9800' : '#4caf50',
                            color: datum.status === 'Remote' ? '#e65100' : '#2e7d32',
                            cornerRadius: 8,
                            padding: 4,
                            fontWeight: 'bold',
                        }),
                    },
                ],
            },
        },
    ],
}

In this configuration:

• title and subtitle display the primary and secondary text with their own key, textAlign, and font styles.
• labels is an array with each entry mapping a data field to a label stacked vertically below the subtitle.
• An itemStyler is used to add a pill-style background to the 'status' label, with the fill and stroke colour determined by the label value.

See the API Reference for the available styling options for each text element.

Image Copy Link

Each node can display an optional image by referencing a data field containing an image URL.

{
    series: [
        {
            type: 'organization',
            node: {
                image: {
                    key: 'avatar',
                    cornerRadius: 25,
                    width: 50,
                    height: 50,
                    position: 'left',
                },
            },
        },
    ],
}

In this configuration:

• key maps to a data field containing an image URL.
• position places the image within the card ('top', 'bottom', 'left', or 'right').
  • The image position dictates the layout of the text within the card.
• width and height control the image dimensions.
• cornerRadius rounds the image corners, allowing rounded rectangles or circles.

Direction Copy Link

{
    series: {
        type: 'organization',
        direction: 'horizontal',
        reverse: false,
    },
}

Expander Copy Link

The expander is displayed on nodes with children and is used to collapse and expand subtrees.

{
    series: [
        {
            type: 'organization',
            expander: {
                text: {
                    showAllChildren: true,
                    showDirectChildren: true,
                },
            },
        },
    ],
}

In this example:

• showAllChildren includes the total count of all descendants in the expander text.
• showDirectChildren includes the count of direct children in the expander text.
• A formatter can be used instead, for full control over the expander text. The params include allChildren, directChildren, depth and isCollapsed alongside the datum.

See the API Reference for more details.

Customisation Copy Link

Node Styling Copy Link

{
    series: [
        {
            type: 'organization',
            node: {
                width: 180,
                cornerRadius: 12,
                itemStyler: ({ datum }) => {
                    if (datum.department === 'Executive')
                        return { fill: '#76B2DC', fillOpacity: 0.2, stroke: '#1B65BF', strokeWidth: 2 };
                    if (datum.department === 'Technology')
                        return { fill: '#7AE281', fillOpacity: 0.2, stroke: '#327C35', strokeWidth: 2 };
                    if (datum.department === 'Operations')
                        return { fill: '#EBB967', fillOpacity: 0.2, stroke: '#A94F1D', strokeWidth: 2 };
                },
            },
        },
    ],
}

In this configuration:

• The width option is used to set the card dimensions. This causes text wrapping when the content exceeds the available space.
• cornerRadius rounds the card corners.
• Each department is assigned a specific colour by using the itemStyler callback based on the department field in the data.

See the API Reference for the full list of available styling options.

Connectors Copy Link

Connectors are the lines drawn between parent and child nodes and are configured via the link property.

{
    series: [
        {
            type: 'organization',
            link: {
                stroke: '#ff8833',
                strokeWidth: 2,
                lineDash: [8, 2],
                interpolation: { type: 'step', cornerRadius: 8 },
                itemStyler: ({ fromDatum }) => {
                    if (fromDatum.department === 'Technology') {
                        return { stroke: '#00994d' };
                    } else if (fromDatum.job === 'CEO') {
                        return { stroke: '#006f9b', strokeWidth: 4, lineDash: [] };
                    }
                },
            },
        },
    ],
}

In this configuration:

• interpolation.cornerRadius rounds the corners of each step.
• lineDash sets a dashed line pattern.
• link.itemStyler styles connectors per-relationship, receiving fromDatum (parent) and toDatum (child).

Expander Copy Link

The expander's appearance can be customised via the expander property. See Expander above for text-content options like child counts and formatter.

{
    series: [
        {
            type: 'organization',
            expander: {
                cornerRadius: 25,
                strokeWidth: 2,
                padding: 15,
                itemStyler: ({ datum }) => {
                    if (datum.department === 'Technology') return { fill: '#e8f5e9', stroke: '#2e7d32' };
                    if (datum.department === 'Operations') return { fill: '#fff3e0', stroke: '#e65100' };
                },
            },
        },
    ],
}

In this configuration:

• cornerRadius, strokeWidth, and padding control the button shape and border.
• expander.itemStyler provides per-node styling based on the department.

Node Spacing Copy Link

Three spacing properties control the gaps between nodes. These values apply at the leaf level, with higher levels in the hierarchy deriving their spacing from these.

{
    series: [
        {
            type: 'organization',
            innerSpacing: 20,
            outerSpacing: 40,
            depthSpacing: 52,
        },
    ],
}

In this configuration:

• innerSpacing is the gap between sibling nodes, such as the gap between 'Lawrence Martinez' and 'Eric Jensen'.
• outerSpacing is the gap between cousin nodes, such as the gap between 'Justin Contreras' and 'Lawrence Martinez'.
• depthSpacing is the gap between parent and child nodes, such as the gap between 'Gary Garcia' and 'Lawrence Martinez'.

Interactivity Copy Link

Collapse and Expand Copy Link

Nodes with children can be collapsed and expanded by clicking the expander. They can also be controlled programmatically.

{
    initialState: {
        collapsed: ['Lawrence Martinez', 'Eric Jensen'],
    },
    series: [
        {
            type: 'organization',
            node: {
                clickToExpand: true,
            },
        },
    ],
    listeners: {
        collapsedChange: ({ collapsed, expanded }) => {
            console.log(
                'collapsed:',
                collapsed.map((item) => item.itemId),
                'expanded:',
                expanded.map((item) => item.itemId)
            );
        },
    },
}

In this example:

• The subtrees under 'Lawrence Martinez' and 'Eric Jensen' will start in a collapsed state. This uses the initialState.collapsed property to specify which subtrees start collapsed.
• Use node.clickToExpand to toggle collapsing/expanding by clicking anywhere on the card instead of the expander only.
  • Defaults to false when node has a click listener or has Data Selection enabled, otherwise defaults to true.
• The collapsed array contains the identifiers of all currently collapsed nodes.
  • See the State API page for more details.
• Changes in the collapsed items can be listened to with the collapsedChange event, logged to the console here showing the itemId of each newly collapsed and expanded node.
  • See the Events API page for more details.

Zoom Copy Link

Organisation Charts have zoom and pan enabled by default. Scroll to zoom in and out, and click and drag the background to pan across the hierarchy.

See the Zoom page for the full range of zoom options.

Accessibility Copy Link

Organisation Charts support full keyboard navigation and screen readers.

The following keys are available:

• ←→↑↓ moves focus between nodes.
• Alt+↓ and Alt+↑ expand and collapse the focused node.
• ↵ Enter or ␣ Space trigger any click listeners, and also toggle the focused node when clickToExpand is enabled.

See Accessibility for more details.

API Reference Copy Link