Overview
TheForceDirected class creates a force-directed network diagram where nodes are positioned using physics-based simulation. Nodes attract or repel each other based on configured forces.
Class Hierarchy
- Series
- Hierarchy
- LinkedHierarchy
- ForceDirected
- LinkedHierarchy
- Hierarchy
Settings
nodePadding
Minimum gap in pixels between the nodes.
centerStrength
A force that attracts (or pushes back) all nodes to the center of the chart.
- Positive values attract nodes to center
- Negative values push nodes away from center
- Higher absolute values = stronger force
manyBodyStrength
A force that attracts (or pushes back) all nodes to each other.
- Negative values make nodes repel each other (typical)
- Positive values make nodes attract each other
- Higher absolute values = stronger force
linkWithStrength
A force that attracts (or pushes back) nodes that are linked together via
linkWithField.Controls the strength of custom links between non-hierarchical nodes.velocityDecay
Resistance acting against node speed.The greater the value, the more “sluggish” the nodes will be.
- Range: 0 to 1
- Higher values = more friction/slower movement
initialFrames
Length of how long initial force simulation would run in frames.The simulation runs for this many frames to settle nodes into position before displaying.
showOnFrame
If set to a number, will wait X number of frames before revealing the tree.Can be used to hide initial animations where nodes settle into their places.
minRadius
Smallest possible radius for a node circle.Can be a fixed pixel value or percent relative to chart size.
maxRadius
Biggest possible radius for a node circle.Can be a fixed pixel value or percent relative to chart size.
xField
Field in data that holds X coordinate of the node.Use to position specific nodes at fixed locations.
yField
Field in data that holds Y coordinate of the node.Use to position specific nodes at fixed locations.
Inherited Settings
ForceDirected inherits all settings from LinkedHierarchy and Hierarchy, including:sort- How to sort nodes by value (“ascending” | “descending” | “none”)valueField- Field in data holding numeric valuecategoryField- Field in data holding category namechildDataField- Field in data holding array of childrendownDepth- Number of child levels to show when drilling downupDepth- Number of parent levels to show from selected nodeinitialDepth- Number of levels to show on first loadtopDepth- Starting level to show (hides upper levels)singleBranchOnly- Collapse other branches when one expandsanimationDuration- Duration for drill animations in millisecondsanimationEasing- Easing function for animationscolors- ColorSet for auto-assigning node colorspatterns- PatternSet for auto-assigning node patternslinkWithField- Field holding IDs of nodes to link with
Data Item Properties
Each data item in a ForceDirected chart has the following properties:children
An array of data items of child nodes.
parent
Data item of a parent node.
x
X coordinate for fixed positioning.When set, the node will be locked to this position.
y
Y coordinate for fixed positioning.When set, the node will be locked to this position.
value
Value of the node as set in data.
sum
Sum of child values.
valuePercentTotal
Percent value of the node, based on total sum of all nodes in upper level.
valuePercent
Percent value of the node, based on the value of its direct parent.Since: 5.2.21
category
Category name of the node.
depth
Node’s depth within the hierarchy (0 for root).
node
Reference to the visual LinkedHierarchyNode element.
circle
Circle element of the node.
outerCircle
Outer circle element of the node (shown for nodes with children).
label
Reference to node’s Label element.
fill
Node’s auto-assigned color.
fillPattern
Node’s auto-assigned pattern.Since: 5.10.0
disabled
Indicates if node is currently disabled (collapsed).
parentLink
HierarchyLink leading to parent node.
childLinks
Array of HierarchyLink objects leading to child nodes.
linkWith
Array of IDs of directly linked nodes (for custom cross-links).
Data Format
Example Data
Example with Fixed Positions
List Templates
ForceDirected provides access to these list templates for customization:nodes
List of all node elements.
circles
List of node circle elements.
outerCircles
List of node outer circle elements (shown for nodes with children).
labels
List of label elements.
links
List of link elements connecting nodes.
Containers
nodesContainer
Container that holds all node elements.
linksContainer
Container that holds all link elements.
Public Properties
d3forceSimulation
The underlying D3 force simulation instance.Advanced users can access this to customize simulation parameters directly.
collisionForce
The collision force that prevents nodes from overlapping.
linkForce
The force that connects linked nodes.
Methods
restartSimulation()
Energy level for the simulation (0 to 1).
updateNodePositions()
updateLinkWith()
linkWith data.
Array of data items to process.
selectDataItem()
The data item to select.
getDataItemById()
The ID to search for.
The found data item, or undefined if not found.
linkDataItems()
Source node data item.
Target node data item.
Optional link strength.
The created or existing link element.
unlinkDataItems()
Source node data item.
Target node data item.
areLinked()
true if two nodes are linked with each other.
Source node data item.
Target node data item.
True if nodes are linked, false otherwise.
enableDataItem()
Target data item to enable.
Maximum depth to enable children to.
Current depth (used internally for recursion).
Animation duration in milliseconds.
disableDataItem()
Target data item to disable.
Animation duration in milliseconds.
addChildData()
Parent data item to add children to.
Array of child data objects.
hoverDataItem()
Target data item.
unhoverDataItem()
Target data item.
Events
dataitemselected
The selected data item.