D3 Force-Directed Layout

Overview

The D3Force layout is a force-directed layout based on d3-force. It simulates physical forces (such as attraction, repulsion, collision, etc.) to make the graph reach a stable state with minimal energy.

The main features of this layout are:

1. Automatic arrangement: No need to manually set node positions, the system will automatically find suitable positions
2. Real-time adjustment: When you drag a node, other nodes will adjust their positions in real time
3. Flexible configuration:
   • You can adjust the attraction and repulsion between nodes
   • You can set the ideal length of edges
   • You can fix the positions of important nodes
4. Animation effect: Nodes move with smooth animation, making changes more natural

Core Concepts

Force System

The D3Force layout simulates five different forces to achieve automatic layout. Imagine a physical world where these forces act simultaneously and eventually reach equilibrium:

Note: The arrows of different colors in the diagram represent different types of forces. In the actual layout, these forces are invisible and also affected by other forces.

• Link Force: Imagine nodes connected by rubber bands, which pull connected nodes to a suitable distance. The tightness of the rubber band is the force strength, and the ideal length is the distance we set.
• Many-Body Force: Similar to magnets, it allows all nodes to attract or repel each other. When the force strength is negative, nodes repel each other (like like poles of magnets); when positive, they attract (like opposite poles). This force determines the density of the graph.
• Center Force: Like all nodes are tied to the center of the canvas by an invisible string. This force prevents nodes from drifting too far and keeps the graph centered.
• Collision Force: Treats nodes as solid balls. When nodes get too close, they automatically bounce apart. This force mainly prevents node overlap and improves readability.
• Radial Force: Imagine an invisible ring that attracts nodes to the ring. By setting the radius and force strength, nodes can form a beautiful circular layout.

Iteration System

Layout calculation is an iterative process with two key concepts:

Alpha Value (Energy)

Like the “energy” of the layout, it determines how vigorously nodes move:

• Initial state: Alpha = 1, nodes move vigorously
• During calculation: Alpha gradually decreases, node movement slows
• End state: When Alpha < alphaMin, nodes stop moving

Iterations

Controls the number of times forces are applied in each calculation:

• Effect: The larger the value, the more precise the layout, but the slower the computation
• Adjustment:
  • Simple graphs: use the default value
  • Complex graphs: increase the number of iterations as needed
  • Real-time interaction: use fewer iterations

Tip: Iterations and alpha value work together. Increasing iterations makes each step more precise, while alpha controls the overall progress.

Options

Iteration Control

Force Model Options

Link Force (link)

Many-Body Force (manyBody)

Center Force (center)

Note: In 5.1, centerX / centerY are the recommended shortcut fields. If you configure the center force directly, it follows the native d3-force style.

Collision Force (collide)

Radial Force (radial)

X Axis Force (x)

Y Axis Force (y)

Code Examples

Prevent Node Overlap

{
  layout: {
    type: 'd3-force',
    collide: {
      // Prevent nodes from overlapping by specifying a collision radius for each node.
      radius: (d) => d.size / 2,
    },
  },
}

See Example - Prevent Node Overlap in Force-Directed Layout

Team Clustering Layout

This example shows how to use force-directed layout for team clustering, where nodes of different teams automatically cluster together.

import { Graph } from '@antv/g6';

const graph = new Graph({
  container: 'container',
  width: 500,
  height: 250,
  autoFit: 'view',
  data: {
    nodes: [
      // Team A
      { id: 'A1', team: 'A', label: 'A1', size: 30 },
      { id: 'A2', team: 'A', label: 'A2', size: 20 },
      { id: 'A3', team: 'A', label: 'A3', size: 20 },
      { id: 'A4', team: 'A', label: 'A4', size: 20 },
      // Team B
      { id: 'B1', team: 'B', label: 'B1', size: 30 },
      { id: 'B2', team: 'B', label: 'B2', size: 20 },
      { id: 'B3', team: 'B', label: 'B3', size: 20 },
      { id: 'B4', team: 'B', label: 'B4', size: 20 },
      // Team C
      { id: 'C1', team: 'C', label: 'C1', size: 30 },
      { id: 'C2', team: 'C', label: 'C2', size: 20 },
      { id: 'C3', team: 'C', label: 'C3', size: 20 },
      { id: 'C4', team: 'C', label: 'C4', size: 20 },
    ],
    edges: [
      // Team A internal connections
      { source: 'A1', target: 'A2' },
      { source: 'A1', target: 'A3' },
      { source: 'A1', target: 'A4' },
      // Team B internal connections
      { source: 'B1', target: 'B2' },
      { source: 'B1', target: 'B3' },
      { source: 'B1', target: 'B4' },
      // Team C internal connections
      { source: 'C1', target: 'C2' },
      { source: 'C1', target: 'C3' },
      { source: 'C1', target: 'C4' },
      // Few connections between teams
      { source: 'A1', target: 'B1' },
      { source: 'B1', target: 'C1' },
    ],
  },
  node: {
    style: {
      size: (d) => d.size,
      fill: (d) => {
        // Different colors for different teams
        const colors = {
          A: '#FF6B6B',
          B: '#4ECDC4',
          C: '#45B7D1',
        };
        return colors[d.team];
      },
      labelText: (d) => d.label,
      labelPlacement: 'center',
      labelFill: '#fff',
    },
  },
  edge: {
    style: {
      stroke: '#aaa',
    },
  },
  layout: {
    type: 'd3-force',
    // Configure link force - nodes within the same team are closer
    link: {
      distance: (d) => {
        // Shorter distance within the same team
        if (d.source.team === d.target.team) return 50;
        // Longer distance between teams
        return 200;
      },
      strength: (d) => {
        // Stronger connection within the same team
        if (d.source.team === d.target.team) return 0.7;
        // Weaker connection between teams
        return 0.1;
      },
    },
    // Configure many-body force - control repulsion between nodes
    manyBody: {
      strength: (d) => {
        // Team leader nodes (ending with 1) have stronger repulsion
        if (d.label.endsWith('1')) return -100;
        return -30;
      },
    },
    // Configure collision force - prevent node overlap
    collide: {
      radius: 35,
      strength: 0.8,
    },
    // Configure center force - keep the graph centered
    center: {
      strength: 0.05,
    },
  },
  behaviors: ['drag-element-force'],
});

graph.render();

import { Graph } from '@antv/g6';
import GUI from 'lil-gui';

export function addPanel(renderPanel: (gui: GUI) => void) {
  const gui = new GUI({ container: document.body });
  gui.title('Control');
  Object.assign(gui.domElement.style, { position: 'absolute', top: '0', right: '0', zIndex: '10' });
  renderPanel(gui);
  addEventListener('pagehide', () => gui.destroy(), { once: true });
}

export async function createGraph(
  options: ConstructorParameters<typeof Graph>[0],
  size: { width?: number; height?: number } = {},
  renderPanel?: (gui: GUI, graph: Graph) => void,
) {
  const container = document.createElement('div');
  Object.assign(container.style, {
    width: '100%',
    maxWidth: `${size.width || 600}px`,
    height: `${size.height || 400}px`,
  });
  document.getElementById('container')!.append(container);
  const graph = new Graph({ ...size, ...options, width: container.clientWidth, container, autoResize: true });
  addEventListener('pagehide', () => graph.destroy(), { once: true });
  await graph.render();
  if (renderPanel) addPanel((gui) => renderPanel(gui, graph));
  return container;
}

import { Graph } from '@antv/g6';

// Create mock data with nodes from different teams
const data = {
  nodes: [
    // Team A
    { id: 'A1', team: 'A', label: 'A1', size: 30 },
    { id: 'A2', team: 'A', label: 'A2', size: 20 },
    { id: 'A3', team: 'A', label: 'A3', size: 20 },
    { id: 'A4', team: 'A', label: 'A4', size: 20 },
    // Team B
    { id: 'B1', team: 'B', label: 'B1', size: 30 },
    { id: 'B2', team: 'B', label: 'B2', size: 20 },
    { id: 'B3', team: 'B', label: 'B3', size: 20 },
    { id: 'B4', team: 'B', label: 'B4', size: 20 },
    // Team C
    { id: 'C1', team: 'C', label: 'C1', size: 30 },
    { id: 'C2', team: 'C', label: 'C2', size: 20 },
    { id: 'C3', team: 'C', label: 'C3', size: 20 },
    { id: 'C4', team: 'C', label: 'C4', size: 20 },
  ],
  edges: [
    // Team A internal connections
    { source: 'A1', target: 'A2' },
    { source: 'A1', target: 'A3' },
    { source: 'A1', target: 'A4' },
    // Team B internal connections
    { source: 'B1', target: 'B2' },
    { source: 'B1', target: 'B3' },
    { source: 'B1', target: 'B4' },
    // Team C internal connections
    { source: 'C1', target: 'C2' },
    { source: 'C1', target: 'C3' },
    { source: 'C1', target: 'C4' },
    // Few connections between teams
    { source: 'A1', target: 'B1' },
    { source: 'B1', target: 'C1' },
  ],
};

const graph = new Graph({
  container: 'container',
  data,
  node: {
    style: {
      size: (d) => d.size,
      fill: (d) => {
        // Different colors for different teams
        const colors = {
          A: '#FF6B6B',
          B: '#4ECDC4',
          C: '#45B7D1',
        };
        return colors[d.team];
      },
      labelText: (d) => d.label,
      labelPlacement: 'center',
      labelFill: '#fff',
    },
  },
  edge: {
    style: {
      stroke: '#aaa',
    },
  },
  layout: {
    type: 'd3-force',
    // Configure link force - nodes within the same team are closer
    link: {
      distance: (d) => {
        // Shorter distance within the same team
        if (d.source.team === d.target.team) return 50;
        // Longer distance between teams
        return 200;
      },
      strength: (d) => {
        // Stronger connection within the same team
        if (d.source.team === d.target.team) return 0.7;
        // Weaker connection between teams
        return 0.1;
      },
    },
    // Configure many-body force - control repulsion between nodes
    manyBody: {
      strength: (d) => {
        // Team leader nodes (ending with 1) have stronger repulsion
        if (d.label.endsWith('1')) return -100;
        return -30;
      },
    },
    // Configure collision force - prevent node overlap
    collide: {
      radius: 35,
      strength: 0.8,
    },
    // Configure center force - keep the graph centered
    center: {
      strength: 0.05,
    },
  },
  behaviors: ['drag-element-force'],
});

graph.render();

Main configuration notes:

• link.distance: Shorter within teams, longer between teams
• link.strength: Stronger within teams, weaker between teams
• manyBody.strength: Controls repulsion between nodes
• collide: Prevents node overlap
• center: Keeps the layout centered

See also Customize parameters for different nodes.