Relation Graph

Global Graph Options (`RGOptions`)

RGOptions defines global relation-graph behavior: interaction modes, default node styles, default line styles, layout configuration, toolbar display, performance mode, and runtime visual effects.

It is not node or line data. It is the graph instance’s set of default rules and runtime parameters.

1. How Options Take Effect

Initial Options

const graphOptions = {
  instanceId: 'main-graph',
  showToolBar: false,
  wheelEventAction: 'scroll',
  dragEventAction: 'move',
  defaultNodeColor: '#ffffff',
  defaultLineColor: '#cbd5e1',
  layout: {
    layoutName: 'center'
  }
};

Pass it to the component:

<RelationGraph options={graphOptions} />

Runtime Option Updates

After the graph is initialized, do not only replace the external reactive options object and expect all behavior to synchronize automatically. Runtime changes should use instance APIs:

graphInstance.updateOptions({
  wheelEventAction: 'zoom',
  dragEventAction: 'selection'
});

You can also use:

graphInstance.setOptions({
  showToolBar: true
});

In the current source code, both setOptions and updateOptions go through _updateOptions() and trigger a view update. When layout is passed, it is merged with the current options.layout and synchronized to the current layouter.

2. Default Values Overview

The main defaults in source function createDefaultConfig() are:

Option	Default	Description
`instanceId`	`''`	Graph instance id. If not set, the framework layer usually generates an instance id. Explicitly set it for SSR or multiple graphs on the same page.
`debug`	`true`	Whether debug output is enabled. The source synchronizes this to `window.relationGraphDebug`.
`showToolBar`	`true`	Whether to show the built-in small toolbar.
`backgroundColor`	`'transparent'`	Graph background color. It is written to CSS variable `--rg-background-color`.
`checkedItemBackgroundColor`	`undefined`	Checked highlight background color. If not set, the CSS default `rgba(150, 150, 150, 0.2)` is used.
`disableWheelEvent`	`false`	Whether to disable normal mouse wheel handling.
`wheelEventAction`	`'zoom'`	Normal wheel behavior. Available values: `'zoom'`, `'scroll'`, `'none'`.
`dragEventAction`	`'move'`	Canvas drag behavior. Available values: `'move'`, `'selection'`, `'none'`.
`fullscreenElementXPath`	`''`	DOM query selector used for fullscreen. If not set, the graph root DOM is used.
`disableDragNode`	`false`	Whether to globally disable node dragging.
`disableDragLine`	`true`	Whether to disable dragging normal lines to move their endpoint nodes.
`canvasMoveMode`	`false`	Internal canvas movement mode state. It is usually maintained automatically during interactions.
`disableNodePointEvent`	`false`	Whether to globally disable node events.
`disableLinePointEvent`	`false`	Whether to globally disable line events.
`enableNodeXYAnimation`	`false`	Whether to animate node position changes. It is usually enabled briefly by the layout flow.
`enableCanvasTransformAnimation`	`false`	Whether to animate canvas pan/zoom transforms.
`reLayoutWhenExpandedOrCollapsed`	`false`	Whether to automatically re-layout after expanding or collapsing a node.
`defaultExpandHolderPosition`	`'hide'`	Default expand/collapse button position.
`toolBarDirection`	`'h'`	Built-in toolbar direction.
`toolBarPositionH`	`'left'`	Built-in toolbar horizontal position.
`toolBarPositionV`	`'bottom'`	Built-in toolbar vertical position.
`defaultNodeColor`	`'#ffffff'`	Default node background color.
`defaultNodeBorderColor`	`'#666666'`	Default node border color.
`defaultNodeBorderWidth`	`1`	Default node border width.
`defaultNodeBorderRadius`	`4`	Default node border radius.
`defaultNodeShape`	`RGNodeShape.rect`	Default node shape.
`defaultNodeWidth`	`undefined`	Default node width. If not set, content/DOM measurement decides the width.
`defaultNodeHeight`	`undefined`	Default node height. If not set, content/DOM measurement decides the height.
`defaultLineColor`	`'#cccccc'`	Default line color.
`defaultLineWidth`	`2`	Default line width.
`defaultLineShape`	`RGLineShape.StandardStraight`	Default line shape.
`defaultLineTextOffsetX`	`undefined`	Default line text X offset. If not set, it is calculated as `0`.
`defaultLineTextOffsetY`	`undefined`	Default line text Y offset. If not set, it is calculated as `0`.
`defaultJunctionPoint`	`RGJunctionPoint.border`	Default rule for line endpoint connection positions.
`defaultLineJunctionOffset`	`3`	Default outward offset from the node boundary for line endpoints.
`defaultPolyLineRadius`	`5`	Default rounded corner radius for polyline segments.
`placeOtherGroup`	`true`	Whether auto layout should also place connected groups and isolated nodes outside the main network.
`defaultLineTextOnPath`	`false`	Whether line text uses SVG `textPath` by default.
`lineTextMaxLength`	`66`	Maximum displayed line text length. Longer text is truncated and followed by `...`.
`multiLineDistance`	`30`	Spacing between multiple lines that connect the same node pair.
`layout`	`{ layoutName: 'center' }`	Default layout configuration.
`canvasZoom`	`100`	Current canvas zoom percentage. This is runtime state and is usually not used as initial configuration.
`mouseWheelSpeed`	`10`	Speed factor for wheel zooming/scrolling.
`minCanvasZoom`	`5`	Minimum zoom percentage.
`maxCanvasZoom`	`500`	Maximum zoom percentage.
`performanceMode`	`false`	Performance mode. At low zoom levels, EasyView may be enabled to reduce DOM rendering pressure.
`viewHeight`	`'100%'`	Graph view height. The root node inline style uses it.

3. Interaction Options

`wheelEventAction`

Controls wheel behavior when the user is not holding Ctrl/Cmd.

Value	Description
`'zoom'`	Default. The wheel zooms the canvas.
`'scroll'`	The wheel pans the canvas, similar to scrolling the canvas view. Holding Ctrl/Cmd still goes through zoom logic.
`'none'`	Normal wheel events are not handled.

Related options:

disableWheelEvent: true: normal wheel events do not respond. In the source, the Ctrl/Cmd zoom path can still enter later processing, so the exact behavior depends on the event and browser environment.
mouseWheelSpeed: wheel zoom/scroll speed. Default is 10. The source applies upper/lower bounds to the zoom step.
minCanvasZoom/maxCanvasZoom: limit the final zoom percentage.

`dragEventAction`

Controls what happens when the user presses and drags on an empty area of the canvas.

Value	Description
`'move'`	Default. Dragging moves the canvas.
`'selection'`	Dragging creates a selection rectangle.
`'none'`	The canvas is not moved and no selection rectangle is created. The source handles it as a canvas click.

Additional rules:

Even when dragEventAction is 'move', dragging while holding Shift enters selection mode.
If the current event target is a line, input, or certain editor element, the source handles the corresponding object logic first.

Dragging and Event Disabling

Option	Default	Description
`disableDragNode`	`false`	Globally disables node dragging. A single node can also set `node.disableDrag`.
`disableDragLine`	`true`	Disables dragging a line to move its endpoint nodes. When set to `false`, dragging a normal line moves both endpoint nodes.
`disableNodePointEvent`	`false`	Globally disables node event hit testing. A single node can override it with `node.disablePointEvent`.
`disableLinePointEvent`	`false`	Globally disables line event hit testing. A single line can override it with `line.disablePointEvent`.

Effective priority:

Node events: if node.disablePointEvent is not set, options.disableNodePointEvent is used.
Node dragging: if either node.disableDrag or options.disableDragNode is true, the node cannot be dragged.
Line events: if line.disablePointEvent is not set, options.disableLinePointEvent is used.

4. Default Node Options

Option	Type	Default	Effect
`defaultNodeColor`	`string`	`'#ffffff'`	Background color used when a node does not set `color`. Also written to a root CSS variable.
`defaultNodeBorderColor`	`string`	`'#666666'`	Border color used when a node does not set `borderColor`.
`defaultNodeBorderWidth`	`number`	`1`	Border width used when a node does not set `borderWidth`.
`defaultNodeBorderRadius`	`number`	`4`	Border radius used when a node does not set `borderRadius`.
`defaultNodeShape`	`RGNodeShape`	`RGNodeShape.rect`	Shape used when a node does not set `nodeShape`. It affects default rendering, line intersection points, and minimaps.
`defaultNodeWidth`	`number \| undefined`	`undefined`	Used when a node does not set `width`. If not set, DOM content measurement decides the width.
`defaultNodeHeight`	`number \| undefined`	`undefined`	Used when a node does not set `height`. If not set, DOM content measurement decides the height.
`defaultExpandHolderPosition`	`'hide' \| 'left' \| 'top' \| 'right' \| 'bottom'`	`'hide'`	Position of the expand/collapse button when a node does not set `expandHolderPosition`.
`checkedItemBackgroundColor`	`string \| undefined`	`undefined`	Highlight background color for checked nodes/lines. It maps to `--rg-checked-item-bg-color`.

Available RGNodeShape values:

Enum	Numeric value	Description
`RGNodeShape.circle`	`0`	Circular node. Line intersection points are calculated against the circle/ellipse boundary.
`RGNodeShape.rect`	`1`	Rectangular node. This is the default.

Example:

const graphOptions = {
  defaultNodeShape: RGNodeShape.rect,
  defaultNodeColor: '#f8fafc',
  defaultNodeBorderColor: '#64748b',
  defaultNodeBorderWidth: 1,
  defaultNodeBorderRadius: 6,
  defaultNodeWidth: 140,
  defaultNodeHeight: 48,
  defaultExpandHolderPosition: 'right'
};

Notes:

Default options only take effect when the node does not set the corresponding field.
Modifying defaults after nodes are created does not necessarily rewrite old node fields to new values. Root CSS variables and effective value conversion can still reflect part of the runtime effect.
Minimap/EasyView depend more on data fields and effective values. Do not express core node colors only through slot CSS.

5. Default Line Options

Option	Type	Default	Effect
`defaultLineColor`	`string`	`'#cccccc'`	Color used when a line does not set `color`.
`defaultLineWidth`	`number`	`2`	Width used when a line does not set `lineWidth`.
`defaultLineShape`	`RGLineShape`	`RGLineShape.StandardStraight`	Path shape used when a line does not set `lineShape`.
`defaultJunctionPoint`	`RGJunctionPoint`	`RGJunctionPoint.border`	Endpoint connection rule used when a line does not set one.
`defaultLineJunctionOffset`	`number`	`3`	Default outward offset from the node boundary for line endpoints.
`defaultPolyLineRadius`	`number`	`5`	Default rounded corner radius for polylines.
`defaultLineTextOnPath`	`boolean`	`false`	Whether text follows the path when a line does not set `useTextOnPath`.
`defaultLineTextOffsetX`	`number \| undefined`	`undefined`	Default line text X offset. If not set, it is calculated as `0`.
`defaultLineTextOffsetY`	`number \| undefined`	`undefined`	Default line text Y offset. If not set, it is calculated as `0`.
`lineTextMaxLength`	`number`	`66`	Maximum line text length before truncation.
`multiLineDistance`	`number`	`30`	Spacing between multiple lines for the same node pair.
`defaultLineMarker`	`object`	See below	Default SVG arrow marker.

Available RGLineShape values:

Enum	Numeric value	Description
`RGLineShape.StandardStraight`	`1`	Standard straight line.
`RGLineShape.Curve2`	`2`	Curve variant.
`RGLineShape.Curve3`	`3`	Curve variant.
`RGLineShape.Curve5`	`5`	Curve variant.
`RGLineShape.StandardCurve`	`6`	Standard curve.
`RGLineShape.Curve7`	`7`	Curve variant.
`RGLineShape.Curve8`	`8`	Special curve variant.
`RGLineShape.SimpleOrthogonal`	`4`	Simple orthogonal polyline.
`RGLineShape.StandardOrthogonal`	`44`	Standard orthogonal line, suitable for editing control points.
`RGLineShape.HardOrthogonal`	`49`	Orthogonal line with fixed control points.

Available RGJunctionPoint values:

Enum	Value	Description
`RGJunctionPoint.border`	`'border'`	Automatically calculate the boundary intersection point. This is the default.
`RGJunctionPoint.ltrb`	`'ltrb'`	Choose an intersection point from the left/top/right/bottom sides of a rectangle.
`RGJunctionPoint.tb`	`'tb'`	Choose only from the top/bottom sides.
`RGJunctionPoint.lr`	`'lr'`	Choose only from the left/right sides.
`RGJunctionPoint.left`	`'left'`	Fixed to the left side.
`RGJunctionPoint.right`	`'right'`	Fixed to the right side.
`RGJunctionPoint.top`	`'top'`	Fixed to the top side.
`RGJunctionPoint.bottom`	`'bottom'`	Fixed to the bottom side.

Default arrow:

defaultLineMarker: {
  viewBox: '0 0 12 12',
  markerWidth: 20,
  markerHeight: 20,
  refX: 3,
  refY: 3,
  data: 'M 0 0, V 6, L 4 3, Z'
}

These fields are used for the built-in <marker> definition. A single line can also use startMarkerId/endMarkerId to reference your own marker.

6. Toolbar and View Options

Option	Default	Available values	Description
`showToolBar`	`true`	`boolean`	Whether to show the built-in toolbar.
`toolBarDirection`	`'h'`	`'h' \| 'v'`	Toolbar arrangement direction. `h` means horizontal, `v` means vertical.
`toolBarPositionH`	`'left'`	`'left' \| 'center' \| 'right'`	Toolbar horizontal position.
`toolBarPositionV`	`'bottom'`	`'top' \| 'center' \| 'bottom'`	Toolbar vertical position.
`viewHeight`	`'100%'`	CSS height string	Graph view height.
`backgroundColor`	`'transparent'`	CSS color	Graph background color.
`fullscreenElementXPath`	`''`	CSS selector string	Preferred target element when calling `fullscreen()`.

Example:

const graphOptions = {
  showToolBar: true,
  toolBarDirection: 'v',
  toolBarPositionH: 'right',
  toolBarPositionV: 'top',
  backgroundColor: '#f8fafc'
};

7. Layout Configuration `layout`

layout is the default layout parameter object. It is used in these scenarios:

Automatically calling doLayout(data.rootId) after setJsonData(data).
Manually calling doLayout().
Re-layout after appendJsonData(data, true).
The layout phase of applyInitialData(data).

Basic structure:

const graphOptions = {
  layout: {
    layoutName: 'tree'
  }
};

Supported layoutName values:

Value	Description
`'center'`	Center layout. This is the default layout. It inherits force layout capability and can support automatic layout.
`'force'`	Force-directed layout.
`'tree'`	Tree layout.
`'circle'`	Circular layout.
`'fixed'`	Fixed layout. It does not automatically change node coordinates.
`'smart-tree'`	Smart tree layout.
`'io-tree'`	Input/output tree layout.
`'folder'`	Folder/directory-style layout.

Common layout fields:

Field	Type	Description
`layoutName`	`string`	Layout name.
`layoutDirection`	`'h' \| 'v'`	Layout direction. `h` means horizontal, `v` means vertical. Some layouts infer or ignore it.
`fixedRootNode`	`boolean`	Whether the root node position is used as a layout anchor. The main layout flow in the source sets this to `true`.
`rotate`	`number`	Layout rotation angle. The exact effect depends on the layouter.
`alignItemsX`	`'start' \| 'center' \| 'end'`	Align node coordinates along the X axis to start/center/end.
`alignItemsY`	`'start' \| 'center' \| 'end'`	Align node coordinates along the Y axis to start/center/end.
`autoLayouting`	`boolean`	Runtime read-only state indicating whether automatic layout is running.
`supportAutoLayout`	`boolean`	Runtime state indicating whether the current layout supports automatic layout.

Tree layout fields:

Field	Type	Default / description
`from`	`'left' \| 'top' \| 'right' \| 'bottom'`	Defaults to `'left'` when filled by the layout. Indicates which direction the tree expands from.
`treeNodeGapH`	`number`	Horizontal gap between nodes.
`treeNodeGapV`	`number`	Vertical gap between nodes.
`levelGaps`	`number[]`	Distance between levels. When the array is insufficient, later calculation logic is usually reused.
`layoutExpansionDirection`	`'start' \| 'center' \| 'end'`	Alignment of same-level nodes relative to their parent.
`simpleTree`	`boolean`	Whether to expand as a one-way simple tree.
`ignoreNodeSize`	`boolean`	Whether to ignore actual node size during layout.
`alignParentItemsX`	`'start' \| 'center' \| 'end'`	Parent node alignment along the X axis.
`alignParentItemsY`	`'start' \| 'center' \| 'end'`	Parent node alignment along the Y axis.

Force/center layout fields:

Field	Type	Description
`fastStart`	`boolean`	Whether force layout starts from a faster initial state.
`maxLayoutTimes`	`number`	Maximum number of iterations.
`byNode`	`boolean`	Whether node-to-node repulsion is enabled.
`byLine`	`boolean`	Whether line elasticity is enabled.
`force_node_repulsion`	`number`	Node repulsion coefficient. Larger values usually spread nodes farther apart.
`force_line_elastic`	`number`	Line elasticity coefficient. Larger values usually pull nodes closer together.
`distanceCoefficient`	`number`	Ideal distance coefficient for center layout.
`disableAsForceLayout`	`boolean`	Whether center layout disables its inherited force layout capability.
`levelGaps`	`number[]`	Center/hierarchical distance control.

Example:

const graphOptions = {
  layout: {
    layoutName: 'tree',
    from: 'left',
    treeNodeGapH: 180,
    treeNodeGapV: 40,
    levelGaps: [120, 180, 220],
    layoutExpansionDirection: 'center'
  }
};

8. Multiple Groups and Isolated Nodes

placeOtherGroup defaults to true.

Effect:

doLayout() first finds the main relationship network from the root node.
Other connected groups outside the main network are laid out separately.
Isolated nodes are placed in a simple grid.
The final groups are arranged in a grid to avoid all groups stacking together.

Set it to false:

graphInstance.updateOptions({
  placeOtherGroup: false
});

This is useful when you only want to lay out the main network containing the root node and keep other nodes at their original positions.

The type definition still keeps placeOtherNodes, but the current layout implementation reads placeOtherGroup. New code should use placeOtherGroup.

9. Performance and Animation Options

Option	Default	Description
`performanceMode`	`false`	Performance mode. At low zoom levels, simplified EasyView may be enabled to reduce the rendering cost of many DOM nodes and lines.
`enableNodeXYAnimation`	`false`	Node position animation. Instance APIs `enableNodeXYAnimation()` / `disableNodeXYAnimation()` can control it.
`enableCanvasTransformAnimation`	`false`	Canvas transform animation. Instance APIs `enableCanvasAnimation()` / `disableCanvasAnimation()` can control it.
`reLayoutWhenExpandedOrCollapsed`	`false`	Whether to automatically call layout after node expansion/collapse.

Performance mode details:

The source switches showEasyView when zoom crosses approximately 40%.
showEasyView is internal runtime state and is not recommended as initial configuration.
In performance mode, the DOM may not contain the complete node/line collection. Be careful with custom statistics or screenshot logic that depends on DOM completeness.

Animation recommendations:

Briefly enabling node animation during automatic layout can improve visual continuity.
For high-frequency real-time data updates, do not keep animation enabled for long periods because it can affect performance and interaction responsiveness.

10. Loading and Runtime Internal State

These fields appear in RGOptionsFull, but they are better treated as runtime state rather than normal initial configuration:

Field	Description	Recommended operation
`graphLoading`	Whether to show the loading mask.	Use `graphInstance.loading(text)` / `clearLoading()`.
`graphLoadingText`	Loading text.	Set it through `loading(text)`.
`checkedNodeId`	Current checked node id.	Use `setCheckedNode()` / `clearChecked()`.
`checkedLineId`	Current checked line id.	Use `setCheckedLine()` / `clearChecked()`.
`draggingNodeId`	Current dragging node id.	Maintained internally.
`creatingSelection`	Whether the user is creating a selection rectangle.	Maintained internally.
`selectionView`	Selection rectangle.	Read through events or hooks.
`creatingNodePlot`	Whether the user is creating a node.	Maintained by node creation interaction.
`newNodeTemplate`	Current new node template.	Maintained by node creation interaction.
`creatingLinePlot`	Whether the user is creating a line.	Maintained by line creation interaction.
`newLineTemplate`	Current new line template.	Maintained by line creation interaction.
`newLinkTemplate`	Current new link template.	Maintained internally.
`editingController`	Node editing controller state.	Use through editing APIs or hooks.
`editingLineController`	Line editing controller state.	Use through editing APIs or hooks.
`nodeConnectController`	Node connection controller state.	Maintained by internal/editor components.
`showMiniView`	Whether the minimap is mounted.	Maintained by `RGMiniView` mounting state.
`showReferenceLine`	Whether alignment reference lines are enabled.	Maintained by reference line component mounting state.
`snapshotting`	Whether screenshot/export is in progress.	Maintained internally.

11. Recommended Option Templates

Read-only Display Graph

const graphOptions = {
  instanceId: 'readonly-graph',
  showToolBar: true,
  wheelEventAction: 'zoom',
  dragEventAction: 'move',
  defaultNodeColor: '#ffffff',
  defaultNodeBorderColor: '#cbd5e1',
  defaultNodeBorderWidth: 1,
  defaultNodeBorderRadius: 6,
  defaultLineColor: '#94a3b8',
  defaultLineWidth: 2,
  defaultLineShape: RGLineShape.StandardCurve,
  minCanvasZoom: 20,
  maxCanvasZoom: 300,
  layout: {
    layoutName: 'center'
  }
};

Graph Editor

const graphOptions = {
  instanceId: 'editor-graph',
  showToolBar: false,
  wheelEventAction: 'scroll',
  dragEventAction: 'selection',
  disableDragNode: false,
  disableDragLine: true,
  disableLinePointEvent: false,
  defaultExpandHolderPosition: 'right',
  defaultNodeWidth: 140,
  defaultNodeHeight: 48,
  defaultLineShape: RGLineShape.StandardOrthogonal,
  defaultJunctionPoint: RGJunctionPoint.border,
  multiLineDistance: 36,
  reLayoutWhenExpandedOrCollapsed: false,
  layout: {
    layoutName: 'fixed'
  }
};

Tree Graph

const graphOptions = {
  instanceId: 'tree-graph',
  wheelEventAction: 'zoom',
  dragEventAction: 'move',
  defaultLineShape: RGLineShape.StandardOrthogonal,
  defaultJunctionPoint: RGJunctionPoint.lr,
  layout: {
    layoutName: 'tree',
    from: 'left',
    treeNodeGapH: 180,
    treeNodeGapV: 30,
    layoutExpansionDirection: 'center'
  }
};

12. Common Misunderstandings

Why does directly modifying the `options` object not take effect?

Runtime updates should call:

graphInstance.updateOptions({ wheelEventAction: 'scroll' });

Do not only replace an external variable.

Why did old nodes not fully change after I changed the default node color?

If an old node already has its own color, it takes precedence over the default value. Defaults only apply when the object does not set the corresponding field.

Why are nodes not automatically arranged after `layoutName: 'fixed'`?

This is expected. The fixed layout means existing node x/y values are used and new coordinates are not calculated automatically.

Why is custom DOM analysis incomplete after enabling `performanceMode`?

Performance mode may switch to EasyView or render only part of the DOM. It is not recommended when you need complete DOM analysis, complex screenshots, or fine-grained interactions.

Global Graph Options (RGOptions)

1. How Options Take Effect

Initial Options

Runtime Option Updates

2. Default Values Overview

3. Interaction Options

wheelEventAction

dragEventAction

Dragging and Event Disabling

4. Default Node Options

5. Default Line Options

6. Toolbar and View Options

7. Layout Configuration layout

8. Multiple Groups and Isolated Nodes

9. Performance and Animation Options

10. Loading and Runtime Internal State

11. Recommended Option Templates

Read-only Display Graph

Graph Editor

Tree Graph

12. Common Misunderstandings

Why does directly modifying the options object not take effect?

Why did old nodes not fully change after I changed the default node color?

Why are nodes not automatically arranged after layoutName: 'fixed'?

Why is custom DOM analysis incomplete after enabling performanceMode?

13. Next Reading

Global Graph Options (`RGOptions`)

`wheelEventAction`

`dragEventAction`

7. Layout Configuration `layout`

Why does directly modifying the `options` object not take effect?

Why are nodes not automatically arranged after `layoutName: 'fixed'`?

Why is custom DOM analysis incomplete after enabling `performanceMode`?