d3-force-attract

Modular force for use with D3's forceSimulation.

Pulls nodes toward a specified ⟨x, y⟩ target point.

Installing

npm

npm install d3-force-attract

CDN, via <script>

<script src="https://wzrd.in/standalone/d3-force-attract@latest"></script>

Local, via <script>

Download the latest release

<script src="./d3-force-attract.min.js"></script>

UNPKG

<script src="https://unpkg.com/d3-force-attract@latest"></script>

Usage

Accessing the module

The install method you use determines the syntax for accessing the module in your code:

npm

Import the forceAttract() method and use it in a forceSimulation.

import { forceAttract } from 'd3-force-attract'
// ...
d3.forceSimulation
    .force('attract', forceAttract());

via <script>, UNPKG

The forceAttract() method is available in the global d3 namespace.

d3.forceSimulation
    .force('attract', d3.forceAttract());

Using the module

Add an 'attract' force just like you would any other D3 force module:

// add an attract force to pull nodes toward the center of the screen
d3.forceSimulation()
    .force('attract', forceAttract()	// see 'Accessing the module' above for the correct syntax
    .target([width/2, height/2])
    .strength(0.05));

More detailed examples:

• Mouse following
• Centered cluster layout

API

The forceAttract module follows the basic interface described in d3-force, additionally implementing the following:

# attract.initialize(nodes) <>

Assigns the array of nodes to this force. This method is called when a force is bound to a simulation via simulation.force and when the simulation’s nodes change via simulation.nodes. A force may perform necessary work during initialization, such as evaluating per-node parameters, to avoid repeatedly performing work during each application of the force.

# attract.strength([strength]) <>

If strength is specified, sets the force strength to the specified number in the range [0,1] and returns this force. If strength is not specified, returns the current strength, which defaults to 0.1. Um, I guess if strength is negative, this might act as a repulsion force? 🤔 I should try that!

This parameter determines the attraction strength of each node to the specified (via attract.target) target node/position.

# attract.target([target]) <>

If target is specified, sets the target point accessor to the specified two-element array [x, y] or function, re-evaluates the target point accessor for each node, and returns this force. If target is not specified, returns the current target point accessor, which defaults to a function that returns [0, 0].

The target point accessor is invoked for each node in the simulation, being passed the node, its zero-based index, and the array of all nodes (the standard D3 format of (d, i, nodes)). The resulting ⟨x, y⟩ point is then stored internally, such that the target point for each node is only recomputed when the force is initialized or when this method is called with a new target, and not on every application of the force.

Building and testing

Install nvm and npm if you haven't already.

Build with the following commands:

nvm use
npm install
npm run dist

Test with npm run test.