# d3-force-attract

> Attraction force for d3.forceSimulation.

Latest version **0.1.1** (published 2016-11-15) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install d3-force-attract
pnpm add d3-force-attract
yarn add d3-force-attract
bun add d3-force-attract
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2016-11-15 |
| First published | 2016-10-22 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 12 |
| Author | Eric Socolofsky |
| Maintainers | ericsoco |
| Keywords | d3, d3-module, d3-force, layout, graph, attract, infovis, dataviz |

## Links

- npm: https://www.npmjs.com/package/d3-force-attract
- Repository: https://github.com/ericsoco/d3-force-attract
- Homepage: http://ericsoco.github.io/d3-force-attract/
- Issues: https://github.com/ericsoco/d3-force-attract/issues
- npm.io page: https://npm.io/package/d3-force-attract

## Alternatives

- [d3-force-3d](https://npm.io/package/d3-force-3d.md) — 1.0M weekly downloads
- [ng2-charts](https://npm.io/package/ng2-charts.md) — 486.8K weekly downloads
- [@arcgis/core](https://npm.io/package/@arcgis/core.md) — 257.8K weekly downloads
- [react-sparklines](https://npm.io/package/react-sparklines.md) — 249.3K weekly downloads
- [react-native-gifted-charts](https://npm.io/package/react-native-gifted-charts.md) — 182.3K weekly downloads

## Recent versions

- 0.1.1 (latest) — 2016-11-15
- 0.1.0 — 2016-11-05
- 0.0.2 — 2016-10-23
- 0.0.1 — 2016-10-22

## README

# d3-force-attract

Modular force for use with D3's [`forceSimulation`](https://github.com/d3/d3-force#forceSimulation).

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

[![Build Status](https://travis-ci.org/ericsoco/d3-force-attract.svg?branch=master)](https://travis-ci.org/ericsoco/d3-force-attract)


## 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](https://github.com/ericsoco/d3-force-attract/releases/latest)

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

#### [UNPKG](https://unpkg.com/)

`<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](https://unpkg.com/)

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](http://bl.ocks.org)
- [Centered cluster layout](http://bl.ocks.org)


## API

The [`forceAttract`](https://github.com/ericsoco/d3-force-attract/blob/master/lib/forceAttract.js) module follows the [basic interface described in d3-force](https://github.com/d3/d3-force/blob/master/README.md#forces), additionally implementing the following:

<a name="attract_initialize" href="#attract_initialize">#</a> <i>attract</i>.<b>initialize</b>(<i>nodes</i>) [<>](https://github.com/ericsoco/d3-force-attract/blob/master/lib/forceAttract.js#L20 "Source")

Assigns the array of *nodes* to this force. This method is called when a force is bound to a simulation via [*simulation*.force](https://github.com/d3/d3-force/blob/master/README.md#simulation_force) and when the simulation’s nodes change via [*simulation*.nodes](https://github.com/d3/d3-force/blob/master/README.md#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.

<a name="attract_strength" href="#attract_strength">#</a> <i>attract</i>.<b>strength</b>([<i>strength</i>]) [<>](https://github.com/ericsoco/d3-force-attract/blob/master/lib/forceAttract.js#L33 "Source")

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](#attract_target)) target node/position.

<a name="attract_target" href="#attract_target">#</a> <i>attract</i>.<b>target</b>([<i>target</i>]) [<>](https://github.com/ericsoco/d3-force-attract/blob/master/lib/forceAttract.js#L37 "Source")

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](http://nvm.sh) and [npm](http://npmjs.com) if you haven't already.

Build with the following commands:

```bash
nvm use
npm install
npm run dist
```

Test with `npm run test`.

---
_Source: https://npm.io/package/d3-force-attract · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._