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:

npm i @acdh/network-visualization

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

<script src="network-visualization.umd.js"></script>

The UMD build is also available via CDN:

<script src="https://unpkg.com/@acdh/network-visualization@0/lib/network-visualization.umd.js"></script>

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):

<script
  crossorigin
  src="https://unpkg.com/react@16/umd/react.production.min.js"
></script>
<script
  crossorigin
  src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"
></script>
<script
  crossorigin
  src="https://unpkg.com/[email protected]/build/three.min.js"
></script>

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

How to use

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

For a 2D visualization:

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

const MyComponent = props => (
  <div style={{ position: 'relative', width: '600px', height: '600px' }}>
    <Visualization
      graph={{
        nodes: [
          { id: 'n1', label: 'Node 1', type: 't1' },
          { id: 'n2', label: 'Node 2', type: 't2' },
          { id: 'n3', label: 'Node 3', type: 't2' },
        ],
        edges: [
          { id: 'e1', label: 'Edge 1', source: 'n1', target: 'n2', type: 'r1' },
          { id: 'e2', label: 'Edge 2', source: 'n1', target: 'n3', type: 'r1' },
        ],
        types: {
          nodes: [
            { id: 't1', label: 'Category 1', color: '#006699' },
            { id: 't2', label: 'Category 2', color: '#669900' },
          ],
          edges: [{ id: 'r1', label: 'Relation 1', color: '#990066' }],
        },
      }}
    />
  </div>
)

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.:

{
  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:

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

Selection controls

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

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

const MyComponent = props => (
  <div style={{ position: 'relative', width: '600px', height: '600px' }}>
    <Visualization dimensions={3} graph={props.graph} />
  </div>
)

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

Visualization and Visualization3D

| 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<string> | | 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<string> | | Ids of selected nodes | | showNeighborsOnly | bool | false | Only how neighbors of selected nodes | | width | number | container width | Canvas width |

SelectionControls

Has all props from <Visualization />, 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) |