Skip to content
On this page

Node Data

The original node object only requires an id property so d3 can identify the node. Graphly D3 extends this data structure quite a bit to provide additional properties to describe appearance and behavior of any node.

INFO

Using Graphly D3, nodes are rendered using a shape template. More about defining them on the Template API documenation.

Example

A simple example for a node object with most possible properties. Check the sub-sections for more details.

js
const node = {
	id: "node1",
	x: 150,
	y: -30,
	shape: {
		type: "myShape",
		scale: 1,
	},
	gravity: -5000,
	spawn: {
		source: "node2",
		angle: 45,
		distance: 600,
	},
	anchor: {
		type: "soft",
		x: 300,
		y: 100,
	},
	satellite: {
		source: "node2",
		angle: 45,
		distance: 600,
	},
	payload: {
		// put your custom data here
	},
};

Interface

ts
interface Node {
	id: string;
	x?: number;
	y?: number;
	shape: Shape;
	gravity?: number;
	spawn?: Spawn;
	anchor?: Anchor;
	satellite?: Satellite;
	payload?: any;
}

Id & Position

The node id property is a string to uniquely identify a node in the graph.
The node x and y properties are optional and define the position of the node. If not defined the simulation will place them at 0,0 by default except spawn, anchor or satellite properties are set.

INFO

Those is the only property by the vanilla d3 force-simulation data structure.

js
const node = {
	id: "node1",
	x: 150,
	y: -30,
};

Shape

The node shape object property defines the appearance of the node. It requires a type and a scale property to tell Graphly D3 how to render the node.

ts
interface Shape {
	type: string;
	scale: number;
	url?: string;
	bodyResolution?: number;
}
PropertyDescription
typedefines which template to use to render the node (Template API)
scaledefines the relative scale of the node (1 by default)
url?can be used to define a custom remote origin for this specific shape type
bodyResolution?can be used to define the resolution of the gly-body path and how detailed collisions and link distances can be calculated (default is 32)

WARNING

bodyResolution is only available since version 1.1.0

TIP

You can use the scale property to create a visual hierachy of nodes by decreasing the size of less important nodes.

js
const node = {
	id: "node1",
	shape: {
		type: "myShape",
		scale: 1,
	},
};

Gravity

The node gravity property is optional and defines the gravitational force this node applies to other nodes. If not set the envGravity of the force simulation is used.

TIP

This proeprty is handy to fine-tune the forces within the simulation. Otherwise, the default value will suffice and you can just ignore it.

In most cases you want to use a negative value to make the nodes push away from each other since this counteracts the link pulling forces.

js
const node = {
	id: "node1",
	gravity: -5000,
};

Spawn

The node spawn object property is optional and describes how the node should be placed when it is created the first time. This property is used when no position are defined yet and the node should be spawned in relative position to another node.

ts
interface Spawn {
	source: string;
	angle: number;
	distance: number;
}
PropertyDescription
sourceid of the source node to spawn the new node in relative position to
angleangle in degrees. Rotation is clockwise. 0 is above the source node
distancedistance between the centers of the source node and the new node

INFO

This property only gets applied on render() when the node object does not have x, y or fx, fy properties set.

js
const node = {
	id: "node1",
	spawn: {
		source: "node2",
		angle: 45,
		distance: 600,
	},
};

Anchor

The node anchor object property is optional and describes the position to which the node is constantly heading towards.

ts
enum AnchorType {
	Soft = "soft",
	Hard = "hard",
}
interface Anchor {
	type: AnchorType;
	x: number;
	y: number;
}
PropertyDescription
typedefines whether the node moves softly towards the position or is locked to it
xthe x position of the anchor
ythe y position of the anchor

INFO

soft anchors are only heading towards the anchor position and will be affected by the other forces applied to the node.

hard anchors are fixing the node to the anchor position and will not be affected by any other forces. (This will set fx and fy properties on the node object)

js
const node = {
	id: "node1",
	anchor: {
		type: "soft",
		x: 300,
		y: 100,
	},
};
ts
import { AnchorType } from "@livereader/graphly-d3";
const node = {
	id: "node1",
	anchor: {
		type: AnchorType.Soft,
		x: 300,
		y: 100,
	},
};

Satellite

The node satellite object property is optional and can be used to bind one node to another. It will keep a relative position to the source node at all times.

ts
interface Satellite {
	source: string;
	angle: number;
	distance: number;
}
PropertyDescription
sourceid of the source node to spawn the new node in relative position to
angleangle in degrees. Rotation is clockwise. 0 is above the source node
distancedistance between the centers of the source node and the new node

INFO

The satellite nodes will be affected by the other forces like (e.g. gravity or collision) but strive towards the computed position simmilar to a soft anchor.

In case of multiple satellites with a similar target position, the satellites will all strive towards their target position and collide with each other.

js
const node = {
	id: "node1",
	satellite: {
		source: "node2",
		angle: 45,
		distance: 600,
	},
};

Payload

Put all your custom data behind the payload object property and use this data in a template to render the node in the desired way.

INFO

To encapsulate and efficiently monitor data changes to perform the necessary re-rendering of nodes, the node payload is optional.

js
const node = {
	payload: {
		// put your custom data here
	},
};

Playground

Give it a try and see how the different properties influence the appearance and behavior of nodes.

WARNING

Dont change the nodes array name since the playground context depends on it.

INFO

This template uses data about title and color to render the node.

js
payload: {
	title: "Hello\nWorld",
	color: "teal",
}

Graphly D3 Documentation