react-d3-graph

react-d3-graph ·

:book: documentation

Interactive and configurable graphs with react and d3 effortlessly

Donations

If you enjoy this library, please consider supporting me for developing and maintaining it.

Playground

Here a live playground page where you can interactively config your own graph, and generate a ready to use configuration! :sunglasses:

You can also load different datasets and configurations via URL query parameter, here are the links:

• small dataset - small example.
• custom node dataset - sample config with custom views.
• marvel dataset - sample config with directed collapsible graph and custom svg nodes.
• static dataset - small sample config statically positioned nodes.

Do you want to visualize your own data set on the live sandbox? Just submit a PR! You're welcome 😁

Documentation :book:

Full documentation here.

Install

npm install d3@^5.5.0      # if you don't have d3 already
npm install react@^16.4.1  # if you don't have react already

npm install react-d3-graph

About react and d3 peer dependencies

Note that react and d3 are peer-dependencies, this means that the responsibility to install them is delegated to the client. This will give you more flexibility on what versions of d3 and react you want to consume, you just need to make sure that you are compliant with the range of versions that react-d3-graph is compatible with. If you install react-d3-graph without first installing d3 and react you might see the following warnings:

npm WARN react-d3-graph@2.0.1 requires a peer of d3@^5.5.0 but none is installed. You must install peer dependencies yourself. npm WARN react-d3-graph@2.0.1 requires a peer of react@^16.4.1 but none is installed. You must install peer dependencies yourself.

Usage sample

Graph component is the main component for react-d3-graph components, its interface allows its user to build the graph once the user provides the data, configuration (optional) and callback interactions (also optional). The code for the live example can be consulted here.

import { Graph } from "react-d3-graph";

// graph payload (with minimalist structure)
const data = {
    nodes: [{ id: "Harry" }, { id: "Sally" }, { id: "Alice" }],
    links: [{ source: "Harry", target: "Sally" }, { source: "Harry", target: "Alice" }],
};

// the graph configuration, you only need to pass down properties
// that you want to override, otherwise default ones will be used
const myConfig = {
    nodeHighlightBehavior: true,
    node: {
        color: "lightgreen",
        size: 120,
        highlightStrokeColor: "blue",
    },
    link: {
        highlightColor: "lightblue",
    },
};

// graph event callbacks
const onClickGraph = function() {
    window.alert(`Clicked the graph background`);
};

const onClickNode = function(nodeId) {
    window.alert(`Clicked node ${nodeId}`);
};

const onDoubleClickNode = function(nodeId) {
    window.alert(`Double clicked node ${nodeId}`);
};

const onRightClickNode = function(event, nodeId) {
    window.alert(`Right clicked node ${nodeId}`);
};

const onMouseOverNode = function(nodeId) {
    window.alert(`Mouse over node ${nodeId}`);
};

const onMouseOutNode = function(nodeId) {
    window.alert(`Mouse out node ${nodeId}`);
};

const onClickLink = function(source, target) {
    window.alert(`Clicked link between ${source} and ${target}`);
};

const onRightClickLink = function(event, source, target) {
    window.alert(`Right clicked link between ${source} and ${target}`);
};

const onMouseOverLink = function(source, target) {
    window.alert(`Mouse over in link between ${source} and ${target}`);
};

const onMouseOutLink = function(source, target) {
    window.alert(`Mouse out link between ${source} and ${target}`);
};

const onNodePositionChange = function(nodeId, x, y) {
    window.alert(`Node ${nodeId} is moved to new position. New position is x= ${x} y= ${y}`);
};

<Graph
    id="graph-id" // id is mandatory, if no id is defined rd3g will throw an error
    data={data}
    config={myConfig}
    onClickNode={onClickNode}
    onDoubleClickNode={onDoubleClickNode}
    onRightClickNode={onRightClickNode}
    onClickGraph={onClickGraph}
    onClickLink={onClickLink}
    onRightClickLink={onRightClickLink}
    onMouseOverNode={onMouseOverNode}
    onMouseOutNode={onMouseOutNode}
    onMouseOverLink={onMouseOverLink}
    onMouseOutLink={onMouseOutLink}
    onNodePositionChange={onNodePositionChange}
/>;

Contributions

Contributions are welcome, feel free to submit new ideas/features, just open an issue or send me an email or something. If you are more a hands on person, just submit a pull request. Before jumping into coding, please take a look at the contribution guidelines CONTRIBUTING.md.

To run react-d3-graph in development mode you just need to run npm run dev and the interactive sandbox will reload with the changes to the library code, that way you can test your changes not only through unit test but also through a real life example. It's that simple. The development workflow usually should follow the steps:

• Create a branch prefixed with fix/ for bug fixes, feature/ for new features, chore/ or refactor/ for refactoring or tooling and CI/CD related tasks.
• Make sure you are up to date running npm install.
• Run npm run dev.
• Make you changes inside the folder src and the interactive sandbox consumes your changes in real time with webpack-dev-server.
• You can run tests locally with npm run test (for unit tests) or npm run functional:local for e2e tests.
• After you're done, open the Pull Request and describe the changes you've made.

Alternatives (Not what you where looking for?)

Well if you scrolled this far maybe react-d3-graph does not fulfill all your requirements 😭, but don't worry I got you covered! There are a lot of different and good alternatives out there, here is a list with a few alternatives. Btw, not in the previous list but also a valid alternative built by uber uber/react-vis-force.

Changelog

2.4.1

Full Changelog

Special announcement:

• After https://github.com/DefinitelyTyped/DefinitelyTyped/pull/42240 being merged thanks to @hrngoode react-d3-graph is not available on DefinitelyTyped in case you use TypeScript. 🎉 🎉 🎉

Implemented enhancements:

• Make link end marker's width and height configurable #238
• Avoid flashing graph when drag&drop node #237
• Make node.renderLabel available at node level #192

Sandbox & Documentation

• Anchored links per each configuration property starting on version 2.4.0
• Deleting node is sandbox breaks the demo if the number of nodes reaches 0 #287

Fixed bugs:

• Collapsible node with no links errors out on click #292
• Deleting node is sandbox breaks the demo if the number of nodes reaches 0 #287
• onNodePositionChange doesn't always trigger #264
• Custom node example is not loading on the sandbox #252
• Not passing data.links breaks the library while it should throw a custom error #211

Closed issues:

• automaticRearrangeAfterDropNode - play button from live demo #261
• Improve live example by replacing all window.alerts by toasts or other non blocking alerts #241
• Add tooltips to sandbox playground configs #239
• Make use of jest .toMatchSnapshot in library unit tests #236
• link.type only can make effect in global #234
• Node drag and drop methods #204

Merged pull requests:

• Chore: Misc bug bix travis node upgrade #305 (danielcaldas)
• Fix error on collapse for node with no links #293 (vsramanujan)
• Stop node removal when node count reaches 1 #288 (pushpinder107)
• Docs: Added missing event to <Graph /> #286 (mknepprath)
• Fix typos #279 (pushpinder107)
• Adding a parameter in config to be able to disable link force #278 (antoninklopp)
• node_label changes enabled local param for renderLabel #267 (gopherine)
• fix/remove delta validation for onNodePositionChange #266 (Kav91)
• Update docs for automaticRearrangeAfterDropNode prop #262 (danielcaldas)
• Bug/custom nodes sandbox additions #256 (danielcaldas)
• Pass the event of onClickGraph to the prop #254 (jameskfry)
• local link type added #247 (gopherine)
• Fix: data links error #246 (mecm1993)
• Making Marker height and width configurable #245 (SachinVarghese)
• Feature/better sandbox alerts #244 (danielcaldas)
• Fix: Update test with .toMatchSnapshot to test UI #243 (nguyenami)
• Prevent graph flashing when dragging and dropping nodes #242 (danielcaldas)
• Feature/sandbox generate tooltips from jsdoc #240 (danielcaldas)