graph.config
Here you can consult a detailed description of each graph configurable property as well as the default values of those properties.
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 provide a toggle 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: [...]
};
Graph global configurations
(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 (depending on the
highlightDegree
value). All the remaining nodes and links assume opacity value equal to
highlightOpacity
.
(boolean
= false)
🚅🚅🚅 when the user mouse hovers some link that link and the correspondent nodes will be highlighted, this is a similar behavior
to
nodeHighlightBehavior
but for links
(just for historical reference this property was introduced in
v1.0.0
)
.
(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
nodeHighlightBehavior
).
(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.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 8)
|
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. |
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.svg string
(default '')
|
🔍🔍🔍 render custom svg for nodes in alternative to
node.symbolType
. This svg can
be provided as a string to either a remote svg resource or for a local one.
|
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
|
| 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. By default the actual value is obtain by the
following expression:
link.strokeWidth * (1 / transform); // transform is a zoom delta Δ value
|
link.highlightColor string
(default '#d3d3d3')
|
links' color in highlight state. |
// A simple config that uses some properties
const myConfig = {
nodeHighlightBehavior: true,
node: {
color: 'lightgreen',
size: 120,
highlightStrokeColor: 'blue'
},
link: {
highlightColor: 'lightblue'
}
};
// Sorry for the long config description, here's a potato 🥔.
Graph/helper
Offers a series of methods that isolate logic of Graph component and also from Graph rendering methods.
Create d3 forceSimulation to be applied on the graph.
d3-force#forceSimulation
d3-force#simulation_force
Wtf is a force? here
(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.
Get the correct node opacity in order to properly make decisions based on context such as currently highlighted node.
number:
the opacity value for the given node.
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 existent 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<string, Object>:
returns the nodes ready to be used within rd3g with additional properties such as x, y
and highlighted values.
Some integrity validations on links and nodes structure. If some validation fails the function will throw an error.
undefined:
- any: can throw the following error msg: INSUFFICIENT_DATA - msg if no nodes are provided INVALID_LINKS - if links point to nonexistent nodes
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 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.
Encapsulates 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).
Object:
a fully (re)initialized graph state object.
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.
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.
(Object)
this object contains a source and target property for a link that is highlighted at some point in time.
| Name | Description |
|---|---|
highlightedLink.source string
|
id of source node for highlighted link. |
highlightedLink.target string
|
id of target node for highlighted link. |
(number)
value that indicates the amount of zoom transformation.
Object:
returns an object containing the generated nodes and links that form the graph. The result is
returned in a way that can be consumed by es6
destructuring assignment
.
Node/helper
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
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, 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 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}`);
};
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}`);
};
<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}
onMouseOverLink={onMouseOverLink}
onMouseOutLink={onMouseOutLink}/>
Handles d3 'drag' event. more about d3 drag
(Object)
if not undefined it will contain event data.
(number)
index of the node that is being dragged.
undefined:
Configures zoom upon graph with default or user provided values.
https://github.com/d3/d3-zoom#zoom
undefined:
Handler for 'zoom' event within zoom config.
Object:
returns the transformed elements within the svg graph area.
Calls d3 simulation.stop().
https://github.com/d3/d3-force#simulation_stop
undefined:
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).
undefined:
Calls d3 simulation.restart().
https://github.com/d3/d3-force#simulation_restart
undefined:
Graph/renderer
Offers a series of methods that isolate render logic for Graph component.
Node
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
svg='assets/my-svg.svg'
type='square'
className='node'
onClickNode={onClickNode}
onMouseOverNode={onMouseOverNode}
onMouseOutNode={onMouseOutNode} />
Link
Link component is responsible for encapsulating link render.
Extends React.Component
const onClickLink = function(source, target) {
window.alert(`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}`);
};
<Link
source='idSourceNode'
target='idTargetNode'
x1=22
y1=22
x2=22
y2=22
strokeWidth=1.5
stroke='green'
className='link'
opacity=1
onClickLink={onClickLink}
onMouseOverLink={onMouseOverLink}
onMouseOutLink={onMouseOutLink} />
utils
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.