0.4.0
Note about performance
Some of the properties have a major performance impact when toggled while rendering graphs of medium or large dimensions (hundreds or thousand of elements).
These properties are marked with 🚅🚅🚅.
⭐ tip to achieve smoother interactions you may want to set staticGraph to true
Note about granularity
Some of the properties listed in the Node section are marked with 🔍🔍🔍. This means that this properties
have a higher level of granularity. These properties can be defined in the graph payload at a node level. (sample payload below)
const graph = {
nodes: [
{
id: 'id',
color: 'red', // only this node will be red
size: 300, // only this node will have size 300
symbolType: 'diamond' // only this node will have 'diamond' shape
}
],
links: [...]
};
(boolean
= false
)
🚅🚅🚅 when true performing a node drag and drop should automatically
rearrange all nodes positions based on new position of dragged node (note:
staticGraph
should be false).
(number
= 400
)
the height of the (svg) area where the graph will be rendered.
(boolean
= false
)
🚅🚅🚅 when user mouse hovers a node that node and adjacent common
connections will be highlighted. All the remaining nodes and links assume opacity value equal to
highlightOpacity
.
(number
= 1
)
Possible values: 0, 1 or 2
. This value represents the range of the
highlight behavior when some node is highlighted. If the value is set to
0
only the selected node will be
highlighted. If the value is set to
1
the selected node and his 1st degree connections will be highlighted. If
the value is set to
2
the selected node will be highlighted as well as the 1st and 2nd common degree connections.
(number
= 1
)
this value is used to highlight nodes in the network. The lower
the value the more the less highlighted nodes will be visible (related to
highlightBehavior
).
(number
= 8
)
max zoom that can be performed against the graph.
(number
= 0.1
)
min zoom that can be performed against the graph.
(boolean
= false
)
when setting this value to true the graph will be completely static, thus
all forces and drag events upon nodes will produce not effect. Note that, if this value is true the nodes will be
rendered with the initial provided
x and y coordinates
(links positions will be automatically set
from the given nodes positions by rd3g), no coordinates will be calculated by rd3g or subjacent d3 modules.
Name | Description |
---|---|
node.color string
(default '#d3d3d3' )
|
🔍🔍🔍 this is the color that will be applied to the node if no color property is found inside the node itself (yes you can pass a property 'color' inside the node and that color will override the this default one ). |
node.fontSize number
(default 10 )
|
font-size property for all nodes' labels. |
node.fontWeight string
(default 'normal' )
|
font-weight property for all nodes' labels. |
node.labelProperty string
(default 'id' )
|
this is the node property that will be used in runtime to fetch the label content. You just need to add some property (e.g. firstName) to the node payload and then set node.labelProperty to be 'firstName' . |
node.mouseCursor string
(default 'pointer' )
|
cursor property for when some node is mouse hovered. |
node.opacity number
(default 1 )
|
by default all nodes will have this opacity value. |
node.renderLabel boolean
(default true )
|
when set to false no labels will appear along side nodes in the graph. |
node.size number
(default 200 )
|
🔍🔍🔍 defines the size of all nodes. |
node.strokeColor string
(default 'none' )
|
color for the stroke of each node. |
node.strokeWidth number
(default 1.5 )
|
the width of the all node strokes. |
node.symbolType string
(default 'circle' )
|
🔍🔍🔍 the
shape
of the node.
Use the following values under a property
type
inside each node (nodes may have different types, same as colors):
[note] react-d3-graph will map this values to d3 symbols |
node.highlightColor string
(default 'SAME' )
|
color for all highlighted nodes (use string 'SAME' if you want the node to keep its color in highlighted state). |
node.highlightFontSize number
(default 10 )
|
fontSize in highlighted state. |
node.highlightFontWeight string
(default 'normal' )
|
fontWeight in highlighted state. |
node.highlightStrokeColor string
(default 'SAME' )
|
strokeColor in highlighted state. |
node.highlightStrokeWidth number
(default 1.5 )
|
strokeWidth in highlighted state.
|
Name | Description |
---|---|
link.color string
(default '#d3d3d3' )
|
the color for links. |
link.opacity number
(default 1 )
|
the default opacity value for links. |
link.semanticStrokeWidth boolean
(default false )
|
when set to true all links will have
"semantic width"
, this means that the width of the connections will be proportional to the value of each link.
This is how link strokeWidth will be calculated:
strokeWidth += (linkValue * strokeWidth) / 10; |
link.strokeWidth number
(default 1.5 )
|
strokeWidth for all links. |
link.highlightColor string
(default '#d3d3d3' )
|
links' color in highlight state. |
// A simple config that uses some properties
const myConfig = {
highlightBehavior: true,
node: {
color: 'lightgreen',
size: 120,
highlightStrokeColor: 'blue'
},
link: {
highlightColor: 'lightblue'
}
};
// Sorry for the long config description, here's a potato 🥔.
Some methods that help no the process of rendering a node.
Converts a string that specifies a symbol into a concrete instance
of d3 symbol.
https://github.com/d3/d3-shape/blob/master/README.md#symbol
Object
:
concrete instance of d3 symbol (defaults to circle).
Build a d3 svg symbol based on passed symbol and symbol type.
(number
= 80
)
the size of the symbol.
(string
= 'circle'
)
the string containing the type of symbol that we want to build
(should be one of
node.symbolType
).
Object
:
concrete instance of d3 symbol.
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
Extends React.Component
(any)
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
const myConfig = {
highlightBehavior: true,
node: {
color: 'lightgreen',
size: 120,
highlightStrokeColor: 'blue'
},
link: {
highlightColor: 'lightblue'
}
};
// Graph event callbacks
const onClickNode = function(nodeId) {
window.alert('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}`);
};
<Graph
id='graph-id' // id is mandatory, if no id is defined rd3g will throw an error
data={data}
config={myConfig}
onClickNode={onClickNode}
onClickLink={onClickLink}
onMouseOverNode={onMouseOverNode}
onMouseOutNode={onMouseOutNode} />
Handles d3 drag 'end' event.
Handles d3 drag 'start' event.
The tick function simply calls React set state in order to update component and render nodes along time as d3 calculates new node positioning.
Configures zoom upon graph with default or user provided values.
https://github.com/d3/d3-zoom#zoom
Handler for 'zoom' event within zoom config.
Object
:
returns the transformed elements within the svg graph area.
Handles mouse out node event.
(number)
index of the mouse hovered node.
Handles mouse over node event.
(number)
index of the mouse hovered node.
Calls d3 simulation.stop().
https://github.com/d3/d3-force#simulation_stop
This method resets all nodes fixed positions by deleting the properties fx (fixed x) and fy (fixed y). Following this, a simulation is triggered in order to force nodes to go back to their original positions (or at least new positions according to the d3 force parameters).
Calls d3 simulation.restart().
https://github.com/d3/d3-force#simulation_restart
Sets d3 tick function and configures other d3 stuff such as forces and drag events.
Offers a series of methods that isolate logic of Graph component.
Build some Link properties based on given parameters.
(string)
the id of the source node (from).
(string)
the id of the target node (to).
(number)
value that indicates the amount of zoom transformation.
Object
:
returns an object that aggregates all props for creating respective Link component instance.
Build Link components for a given node.
(string)
the id of the node to whom Link components will be generated.
(number)
value that indicates the amount of zoom transformation.
Array<Object>
:
returns the generated array of Link components.
Build some Node properties based on given parameters.
(Object)
the node object for whom we will generate properties.
(number)
value that indicates the amount of zoom transformation.
Object
:
returns object that contain Link props ready to be feeded to the Link component.
Method that actually is exported an consumed by Graph component in order to build all Nodes and Link components.
(Object<string, Object>)
an object containing a matrix of connections of the graph, for each nodeId,
there is an Object that maps adjacent nodes ids (string) and their values (number).
// links example
{
"Androsynth": {
"Chenjesu": 1,
"Ilwrath": 1,
"Mycon": 1,
"Spathi": 1,
"Umgah": 1,
"VUX": 1,
"Guardian": 1
},
"Chenjesu": {
"Androsynth": 1,
"Mycon": 1,
"Spathi": 1,
"Umgah": 1,
"VUX": 1,
"Broodhmome": 1
},
...
}
(string)
this value contains a string that represents the some currently highlighted node.
(number)
value that indicates the amount of zoom transformation.
Object
:
returns an object containg the generated nodes and links that form the graph. The result is
returned in a way that can be consumed by es6
destructuring assignment
.
Create d3 forceSimulation to be applied on the graph.
https://github.com/d3/d3-force#forceSimulation
https://github.com/d3/d3-force#simulation_force
(number)
the width of the container area of the graph.
(number)
the height of the container area of the graph.
Object
:
returns the simulation instance to be consumed.
Incapsulates common procedures to initialize graph.
(Object)
Graph component props, object that holds data, id and config.
Name | Description |
---|---|
props.data Object
|
Data object holds links (array of Link ) and nodes (array of Node ). |
props.id string
|
the graph id. |
props.config Object
|
same as config in buildGraph . |
(Object)
Graph component current state (same format as returned object on this function).
any
:
a fully (re)initialized graph state object.
Receives a matrix of the graph with the links source and target as concrete node instances and it transforms it in a lightweight matrix containing only links with source and target being strings representative of some node id and the respective link value (if non existant will default to 1).
Object<string, Object>
:
an object containing a matrix of connections of the graph, for each nodeId,
there is an object that maps adjacent nodes ids (string) and their values (number).
Method that initialize graph nodes provided by rd3g consumer and adds additional default mandatory properties that are optional for the user. Also it generates an index mapping, this maps nodes ids the their index in the array of nodes. This is needed because d3 callbacks such as node click and link click return the index of the node.
Object
:
returns the nodes ready to be used within rd3g with additional properties such as x, y
and highlighted values. Returns also the index mapping object of type Object.<number, string>.
Node component is responsible for encapsulating node render.
Extends React.Component
const onClickNode = function(nodeId) {
window.alert('Clicked node', nodeId);
};
const onMouseOverNode = function(nodeId) {
window.alert('Mouse over node', nodeId);
};
const onMouseOutNode = function(nodeId) {
window.alert('Mouse out node', nodeId);
};
<Node
id='nodeId'
cx=22
cy=22
fill='green'
fontSize=10
dx=90
fontWeight='normal'
label='label text'
opacity=1
renderLabel=true
size=200
stroke='none'
strokeWidth=1.5
type='square'
className='node'
onClickNode={onClickNode}
onMouseOverNode={onMouseOverNode}
onMouseOutNode={onMouseOutNode} />
Link component is responsible for encapsulating link render.
Extends React.Component
const onClickLink = function(source, target) {
window.alert(`Clicked link between ${source} and ${target}`);
};
<Link
source='idSourceNode'
target='idTargetNode'
x1=22
y1=22
x2=22
y2=22
strokeWidth=1.5
stroke='green'
className='link'
opacity=1
onClickLink={onClickLink} />
Handle link click event.
Offers a series of generic methods for object manipulation, and other operations that are common across rd3g such as error logging.
Generic deep comparison between javascript simple or complex objects.
(Object)
one of the objects to be compared.
(Object)
second object to compare with first.
(number
= 0
)
this parameter serves only for internal usage.
boolean
:
returns true if o1 and o2 have exactly the same content, or are exactly the same object reference.
This function merges two objects o1 and o2, where o2 properties override existent o1 properties, and if o2 doesn't posses some o1 property the fallback will be the o1 property.
(Object
= {}
)
object.
(Object
= {}
)
object that will override o1 properties.
(int
= 0
)
the depth at which we are merging the object.
Object
:
object that is the result of merging o1 and o2, being o2 properties priority overriding
existent o1 properties.