Skip to content
Nodus

Graph: nodes & edges

The graph API is mixed directly onto the Nodus instance — you call nodus.setGraph(...), nodus.getNode(...) and so on. Queries hand back Node / Edge wrappers or NodeList / EdgeList collections.

Graph data shape

setGraph and the parsers accept plain JSON:

type RawGraph = { nodes: RawNode[]; edges: RawEdge[] };


type RawNode = {
  id?: string | number;
  attributes?: Record<string, any>; // visual attributes
  data?: ND;                         // your payload
};


type RawEdge = {
  id?: string | number;
  source: string | number;
  target: string | number;
  attributes?: Record<string, any>; // visual attributes
  data?: ED;                         // your payload
};

attributes holds visual attributes (x, y, color, radius, shape, text, …) — see the attribute catalog. data is your own arbitrary payload, typed via the ND / ED generics; read it with element.getData(path?) and write it with element.setData(pathOrData, value?).

Graph API

Replacing and merging

  • setGraph(graph, opts?) — replace the whole graph. Returns a promise-like.
  • addGraph(graph, opts?) — merge a RawGraph into the current graph.
  • clearGraph() — remove every node and edge.
await nodus.setGraph({
  nodes: [{ id: 'a' }, { id: 'b' }],
  edges: [{ source: 'a', target: 'b' }],
});


await nodus.addGraph({ nodes: [{ id: 'c' }], edges: [{ source: 'b', target: 'c' }] });

Adding elements

  • addNode(el, opts?), addNodes(els, opts?) — add node(s); return the created Node / NodeList.
  • addEdge(el, opts?), addEdges(els, opts?) — add edge(s); return the created Edge / EdgeList.
const n = nodus.addNode({ id: 'd', attributes: { x: 0, y: 0 } });
const list = nodus.addNodes([{ id: 'e' }, { id: 'f' }]);
const e = nodus.addEdge({ source: 'd', target: 'e' });

Removing elements

Each returns Promise<void>.

  • removeNode(el, opts?), removeNodes(els, opts?)
  • removeEdge(el, opts?), removeEdges(els, opts?)
await nodus.removeEdge(e);
await nodus.removeNodes(list);

Querying

  • getNode(id) — a single Node, or undefined.
  • getNodes(filter?) — a NodeList; filter may be a predicate function.
  • getEdge(id) — a single Edge, or undefined.
  • getEdges(filter?) — an EdgeList; filter may be a predicate.
  • getConnectedComponents(opts?) — the graph’s connected components.
  • getConnectedComponentByNode(nodeId, opts?) — the component containing a node.
const hubs = nodus.getNodes().filter((node) => node.getDegree() > 3);
const a = nodus.getNode('a');
const components = nodus.getConnectedComponents();

Node

A Node wraps an internal index into the graph. (Edge mirrors these and adds its endpoints.)

Data and attributes

  • getId()
  • getData(path?), setData(pathOrData, value?)
  • getAttributes(names?), getAttribute(name)
  • setAttributes(attrs, opts?), setAttribute(name, value, opts?)
  • resetAttributes(names?, opts?), getPreviousAttributes(names?)

Position and screen

  • getPosition() -> {x, y}, setPosition({x, y}, opts?)
  • getPositionOnScreen()
  • isInScreen(), isInView(opts?)

Adjacency (Node)

  • getAdjacentNodes(opts?), getAdjacentEdges(opts?), getAdjacentElements(opts?)
  • getDegree(opts?)
  • getConnectedComponent(opts?)

Classes

  • addClass(name, opts?), addClasses(names, opts?), removeClass(name, opts?)
  • hasClass(name), getClassList()

State

  • isSelected(), setSelected(bool)
  • isDisabled(), setDisabled(bool)
  • isVisible(), setVisible(bool)

Style

  • getStyle(name?), setStyle(attrs, opts?), resetStyle(opts?)

Geometry and effects

  • locate(opts?) — pan/zoom the camera to this element.
  • pulse(opts?) — emit an animated pulse from this element.
  • getBoundingBox({ includeTexts? })
  • toJSON(opts?)
const node = nodus.getNode('a');
node.setAttributes({ color: '#0f766e', radius: 18 });
node.setData('visited', true);
node.addClass('highlighted');
await node.locate({ duration: 300 });

Edge

Edge exposes the same methods as Node (data, attributes, classes, state, style, geometry). In addition, an edge knows its endpoints — its source and target nodes — since it is defined by them.

const edge = nodus.getEdge(someId);
edge.setAttributes({ width: 3, color: '#94a3b8', shape: { head: 'arrow' } });

Collections

getNodes() / getEdges() and many queries return a NodeList or EdgeList. They are array-like and immutable to mutate-through helpers (filtering returns a new list).

Access and iteration

  • .size, iterable with for...of
  • .toArray(), .get(i), .clone()

Functional

  • .forEach(fn), .map(fn)
  • .filter(fn) — returns a NodeList / EdgeList
  • .find(fn), .some(fn), .every(fn), .reduce(fn, init)
  • .sort(cmp), .slice(start?, end?)

Set operations

  • .concat(other), .subtract(other), .dedupe(), .inverse()
  • .includes(el), .indexOf(el)

Broadcast

These apply to every member of the list:

  • .setAttributes(attrs), .setData(...), .fillData(...)
  • .addClass(name), .removeClass(name)
  • .setSelected(bool), .setVisible(bool)
  • .locate(), .pulse()
  • .getData(path?) — returns an array
  • .getId() — returns an array
  • .getPosition() — returns an array
  • .getDegree() — returns an array
  • .group(opts?), .ungroup(opts?)
const hubs = nodus.getNodes().filter((n) => n.getDegree() > 3);


console.log(hubs.size);
hubs.setAttributes({ color: '#ef4444' });
hubs.addClass('hub');


const ids = hubs.getId();                 // string[] | number[]
const labels = hubs.map((n) => n.getData('label')); // array of mapped values