@data-ui/network

React + d3 library for creating graph visualizations

Usage no npm install needed!

<script type="module">
  import dataUiNetwork from 'https://cdn.skypack.dev/@data-ui/network';
</script>

README

@data-ui/network

demo at williaster.github.io/data-ui

Overview

This package exports declarative react <Network /> implemented with @vx which can be used to render network.

Usage

See the demo at williaster.github.io/data-ui for more example outputs.

Network Visualization

Components

Check out the example source code and PropTable tabs in the Storybook williaster.github.io/data-ui for more!

<Network />

The Network component renders the network visualization. It takes the following props:

Name Type Default Description
ariaLabel PropTypes.string.isRequired - Accessibility label for the svg
children PropTypes.node.isRequired - Child series, reference lines, defs, or other valid svg children
className PropTypes.string - Optional className to add to the svg
graph PropTypes.shape({nodes: PropTypes.array, links: PropTypes.array }) - A valid graph structure with nodes and links.
height PropTypes.number.isRequired - Height of the svg including top/bottom margin
width PropTypes.number.isRequired - Width of the svg including left/right margin
margin PropTypes.shape({ top: PropTypes.number, right: PropTypes.number, bottom: PropTypes.number, left: PropTypes.number }) { top: 16, right: 16, bottom: 16, left: 16 } Chart margin
onMouseMove PropTypes.func null func({ data, id, event, index }), passed to a NodeComponent
onMouseLeave PropTypes.func null func({ data, id, event, index }), passed to a NodeComponent
onMouseEnter PropTypes.func null func({ data, id, event, index }), passed to a NodeComponent
onClick PropTypes.func null func({ data, id, event, index }), passed to a NodeComponent
waitingForLayoutLabel PropTypes.string 'Computing layout...' Placeholder message when the layout algorithm is running
scaleToFit PropTypes.bool true A flag to indiate if the computed x and y from layout algorithms will be scaled to fit for the graph width and height. If it is false, the perserveAspectRatio won't be used. It is useful when the layout algorithms handle the scale-to-fit functionality.
preserveAspectRatio PropTypes.bool true A flag to indiate if the aspect ratio will be preserved when scaling the layout to fit for the width and height of the component.
renderLink PropTypes.func Link Customized Link Renderer for an link object
renderNode PropTypes.func Node Customized Node Renderer for an node object
layout PropTypes.object atlasForce Customized layout object created by an Layout Class

Layout Class

Users can creat their own layout algorithm class and pass the object created by the class to the network visualization. For a layout class, it must implement the following functions:

Function Parameters Description
setGraph graph: graphShape Assign a graph to the object
getGraph return the graph
layout { callback: function } Layout the graph and call the callback function with the layouted graph as the input parameter.
setAnimated isAnimated: bool Render the graph layout process with animated transition
isAnimated Return the animated status
clear Post-process used to clear any states, such as clear all the callback functions
setBoundingBox { width: number, height: number, margin: marginShape } set width, height, and margin for the layout algorithm.

Tooltips

Tooltips are controlled with the renderTooltip function passed to <Network />. This function takes an object with the shape { event, index, id, data } as input and is expected to return the inner contents of the tooltip (not the tooltip container!) as shown above. If this function returns a falsy value, a tooltip will not be rendered.

Under the covers this will wrap the <Network /> component in the exported <WithTooltip /> HOC, which wraps the svg in a <div /> and handles the positioning and rendering of an HTML-based tooltip with the contents returned by renderTooltip(). This tooltip is aware of the bounds of its container and should position itself "smartly".

Customization

If you'd like more customizability over tooltip rendering you can do either of the following:

  1. Roll your own tooltip positioning logic and pass onMouseMove and onMouseLeave functions to <Network />. These functions are triggered with the signature described below upon appropriate trigger.

  2. Wrap <Network /> with <WithTooltip /> yourself, which accepts props for additional customization:

Name Type Default Description
children PropTypes.func or PropTypes.object - Child function (to call) or element (to clone) with onMouseMove, onMouseLeave, and tooltipData props
className PropTypes.string - Class name to add to the <div> container wrapper
renderTooltip PropTypes.func.isRequired - Renders the contents of the tooltip, signature of ({ event, data, datum, color }) => node. If this function returns a falsy value, a tooltip will not be rendered.
styles PropTypes.object {} Styles to add to the <div> container wrapper
TooltipComponent PropTypes.func or PropTypes.object @vx's TooltipWithBounds Component (not instance) to use as the tooltip container component. It is passed top and left numbers for positioning
tooltipProps PropTypes.object - Props that are passed to TooltipComponent
tooltipTimeout PropTypes.number 200 Timeout in ms for the tooltip to hide upon calling onMouseLeave

Note that to correctly position a tooltip, the <WithTooltip /> onMouseMove function minimally requires an event OR coords object of the form { x: Number, y: Number }. If coords is specified it takes precedent over any position computed from the event. See function signatures below for more.

Functions and Function Signatures

<Network /> supports onMouseEnter, onMouseMove, onMouseLeave, and onClick event handlers. These functions are passed to the renderNode components with the following signatures:

onMouseLeave(event);
allOtherFunc({ event, index, id, data: node, coords] });

coords is an object of the form { x: Number, y: Number }. XYChart passes x and y only if snapTooltipToDataX or snapTooltipToDataY are true, respectively.

Programmatically triggering tooltips

<Network /> exposes hooks to manually trigger any of these handlers with the eventTriggerRefs prop. Similar to React refs, this prop is a callback function that is called by <Network /> after mounting. The callback receives an object as input, with keys corresponding to the event type names and respective handlers as values: eventTriggerRefs({ click, mouseenter, mousemove, mouseleave }). The ref handlers have the same signatures as defined above.

Note that snapTooltipToData* props will still apply (i.e., coords will be passed in the event signature) when events are triggered this way.

Roadmap

  • more layout algorithms
  • dragging interaction enabled