network-visualization

This is a React component to visualize graph data in 2D and 3D. It is based on
force-graph and
3d-force-graph, which use
d3-force and
d3-force-3d for the simulation.

How to install

Install it as a package from NPM:

``sh
npm i @acdh/network-visualization
`

You can also include the UMD build in a script tag, and access the components
on the NetworkVisualization global:

`html

`

The UMD build is also available via CDN:

`html

`

When using the UMD build, make sure to also include react and, if you plan to
use the 3D component, three (note that three does not follow semantic
versioning, last known working version is 0.126.1):

`html
crossorigin
src="https://unpkg.com/react@16/umd/react.production.min.js"
>
crossorigin
src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"
>
crossorigin
src="https://unpkg.com/three@0.126.1/build/three.min.js"
>
`

See the examples folder for how to use the UMD build.

How to use

The package exports three components: the basic and
components, and a component that
wraps the visualization components and handles selecting/deselecting nodes in
the graph.

For a 2D visualization:

`js
import React from 'react'
import { Visualization } from '@acdh/network-visualization'

const MyComponent = props => (



)
`

The graph prop is the only required prop. It must include the graph's nodes
and edges, as well as a types object describing the node and edge types. All
entities in the graph can have an optional label and a color, where labels
and colors defined on individual nodes/edges take precedence over labels and
colors defined for node types/edge types.

Note that nodes, edges, types.nodes and types.edges can be provided as
arrays, or as objects mapped by id, e.g.:

`js
{
nodes: {
n1: {
id: 'n1'
},
n2: {
id: 'n2',
},
},
}
`

When the graph data changes during the lifetime of the component, by default new
nodes and edges will be _added_ to the previously provided graph. If you want to
_replace_ a graph, you can add the replace property to the graph object:

`diff
{
nodes: [],
edges: [],
types: {
edges: [],
nodes: []
},
+ replace: true,
}
`

Selection controls

Click interactions which allow selecting/deselecting nodes can be added with the
component:

`js
import React from 'react'
import { SelectionControls as Visualization } from '@acdh/network-visualization'

const MyComponent = props => (



)
`

By default, SelectionControls is an uncontrolled component, i.e. it holds the
state of selected nodes internally. It is possible to switch it to a controlled
component by providing a Set of ids with the selectedNodeIds prop.

Live example

You can view a live example of the components in storybook, by either locally
running npm run storybook, or
here.

Props

$3

| prop | type | default | description |
| ------------------ | -------------- | ---------------- | --------------------------------------------------------------------------------------------------------------- |
| backgroundColor | string | | Canvas color |
| dagMode | string \| null | null | Layout mode for directed acyclical graphs |
| graph | object | | Graph data, see above for the expected format |
| height | number | container height | Canvas height |
| highlightedNodeIds | Set\ | | Ids of highlighted nodes |
| onNodeClick | function | | Event callback fired when clicking on a node. Receives an object with { node, graph, forceGraph } as argument |
| onSimulationEnd | function | | Event callback fired when simulation ends |
| onSimulationTick | function | | Event callback fired every simulation tick |
| onZoom | function | | Event callback fired on every zoom/pan interaction |
| selectedNodeIds | Set\ | | Ids of selected nodes |
| showNeighborsOnly | bool | false | Only how neighbors of selected nodes |
| width | number | container width | Canvas width |

$3

Has all props from `, and adds:

| prop | type | default | description |
| -------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dimensions | number | 2 | 2D or 3D layout |
| onNodeDeselect | function | | Event callback fired when node is deselected. Receives the node object as argument (and the set of currently selected node ids when used as an uncontrolled component) |
| onNodeSelect | function | | Event callback fired when node is selected. Receives the node object as argument (and the set of currently selected node ids when used as an uncontrolled component) |