Line Data Model (JsonLine / RGLine)

Lines describe relationships between two endpoints. A normal line’s two endpoints must be node ids. If an endpoint is not a node, use FakeLine.

In real projects you will usually work with two line object shapes:

• JsonLine: the line data you pass into the graph.
• RGLine: the runtime line object generated by relation-graph.

1. Minimal Line

A normal line needs at least from and to:

const line = {
  from: 'node-a',
  to: 'node-b'
};

It is recommended to explicitly provide id and text:

const line = {
  id: 'line-a-b',
  from: 'node-a',
  to: 'node-b',
  text: 'calls'
};

Rules:

• from is the start node id.
• to is the end node id.
• id is required in the source type, but when adding a normal line without an id, the runtime generates an id such as L-xxxxxx. For stable updates, deletion, and persistence, business code should set id explicitly.
• The current source code is compatible with older fields: if from is missing but source exists, source is used as from; if to is missing but target exists, target is used as to; if text is missing but label exists, label is used as text. New code should use from/to/text.

2. JsonLine Fields

Identity, Relationship, And Business Fields

Field	Type	Default	Description
id	string	Can be generated when adding, but explicit id is strongly recommended	Unique line id. Queries, updates, deletion, and RGLink association depend on it.
from	string	Required	Start node id. A normal line must resolve to an existing node.
to	string	Required	End node id. A normal line must resolve to an existing node.
text	string	''	Line text. The default line component renders it; custom line slots also usually read it.
type	string	''	Business type. Useful for slot-template dispatch or CSS classification.
data	Record<string, any>	{}	Business extension data. Put weight, status, description, and similar attributes here.
selected	boolean	false	Multi-select/editor state. It differs from the single checked state managed by checkedLineId.

Path Fields

Field	Type	Default	Description
lineShape	RGLineShape	options.defaultLineShape, default RGLineShape.StandardStraight	Line path shape. Affects SVG path generation.
lineDirection	'h' | 'v' | string	Current layout direction or 'h'	Main direction used by polyline/curve calculation. 'h' is horizontal-oriented; 'v' is vertical-oriented.
fromJunctionPoint	RGJunctionPoint	options.defaultJunctionPoint, default border	How the start point intersects with the node.
toJunctionPoint	RGJunctionPoint	options.defaultJunctionPoint, default border	How the end point intersects with the node.
junctionOffset	number	options.defaultLineJunctionOffset, default 3	Offset from the node boundary. It can move line endpoints farther from or closer to the node edge.
fromJunctionPointOffsetX	number	0	Extra X offset for the start junction point.
fromJunctionPointOffsetY	number	0	Extra Y offset for the start junction point.
toJunctionPointOffsetX	number	0	Extra X offset for the end junction point.
toJunctionPointOffsetY	number	0	Extra Y offset for the end junction point.
lineRadius	number	options.defaultPolyLineRadius, default 5	Polyline corner radius, mainly affecting orthogonal/polyline paths.
polyLineStartDistance	number	Unset	Start segment distance for simple polylines, mainly used by SimpleOrthogonal paths.

RGLineShape values:

Enum	Value	Description
RGLineShape.StandardStraight	1	Standard straight line. The simplest path, suitable for dense or simple relationship graphs.
RGLineShape.Curve2	2	Curve variant. Uses the generic curve generator and appears softer than a straight line.
RGLineShape.Curve3	3	Curve variant. Useful when you need a visually distinct curve.
RGLineShape.Curve5	5	Curve variant.
RGLineShape.StandardCurve	6	Standard curve. It is also a fallback shape for some self-loop or same-point cases.
RGLineShape.Curve7	7	Curve variant.
RGLineShape.Curve8	8	Special curve generator.
RGLineShape.SimpleOrthogonal	4	Simple orthogonal polyline. Common in tree and flow diagrams.
RGLineShape.StandardOrthogonal	44	Standard orthogonal line, with more complete orthogonal path and edit-control-point support.
RGLineShape.HardOrthogonal	49	Forced/fixed-control-point orthogonal line, often generated or used by path editing.

RGJunctionPoint values:

Enum	Value	Description
RGJunctionPoint.border	'border'	Automatically calculates the intersection on the node boundary. Default and suitable for most cases.
RGJunctionPoint.ltrb	'ltrb'	Selects a rectangular intersection from left, top, right, and bottom boundaries.
RGJunctionPoint.tb	'tb'	Only selects top/bottom boundaries. Suitable for vertical trees.
RGJunctionPoint.lr	'lr'	Only selects left/right boundaries. Suitable for horizontal trees.
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.

The source code also contains internal branches for 'horizontalLine' and 'verticalLine' for special line/point scenarios. Do not rely on them as public business configuration.

Color, Width, And Text Style Fields

Field	Type	Default	Description
color	string	options.defaultLineColor, default #cccccc	Line color. Affects SVG stroke and the default arrow color.
lineWidth	number	options.defaultLineWidth, default 2	Line width.
opacity	number	1	Line opacity. Recommended range is 0 to 1.
className	string	undefined	Extra class added to the line DOM. Useful for theme or state styling.
fontColor	string	CSS default or inherited line color	Line text color.
fontSize	number	CSS default, usually 12px	Line text font size.
textOffsetX	number	options.defaultLineTextOffsetX or 0	X offset for line text.
textOffsetY	number	options.defaultLineTextOffsetY or 0	Y offset for line text. When using textPath, the source code applies an additional -6 vertical correction.
placeText	'start' | 'center' | 'end' | string	Middle by default	Controls text placement along the path. When using textPath, percentage strings such as '30%' are also supported.
textAnchor	string	Normal text is treated as 'center'; textPath defaults to 'middle'	Text anchor. Common values: 'start', 'middle', 'end'.
useTextOnPath	boolean	options.defaultLineTextOnPath, default false	Whether to use SVG textPath so text follows the line. Straight lines are handled as normal rotated text; non-straight paths are better candidates.

Text truncation:

• options.lineTextMaxLength defaults to 66.
• Text longer than that is truncated and suffixed with ....
• If you need full text, render a tooltip or multi-line label in a custom line slot.

Arrow And Built-In Effect Fields

Field	Type	Default	Description
showStartArrow	boolean	false	Whether to show the start arrow.
showEndArrow	boolean	true	Whether to show the end arrow.
startMarkerId	string	''	Custom start SVG marker id. When set, it takes priority.
endMarkerId	string	''	Custom end SVG marker id. When set, it takes priority.
dashType	number	0	Dashed-line preset type. It generates a class such as rg-line-dashtype-{dashType}; the visual result comes from built-in CSS or your CSS.
animation	number	0	Animation preset type. It generates a class such as rg-line-anm-{animation}; the animation is defined by CSS.
cssVars	Record<string, any>	Unset	Per-line CSS variable extension for advanced styling.

Arrow rules:

• End arrow is shown by default; start arrow is not.
• If no custom markerId is provided, the graph instance uses its built-in default arrow.
• line.isReverse is a runtime internal field. When it exists, arrow directions are swapped during rendering. Do not persist or manually rely on it.

Behavior And Layout Impact Fields

Field	Type	Default	Description
disablePointEvent	boolean	Follows options.disableLinePointEvent when unset; often false after import	Disables event hit testing for this line.
hidden	boolean	false	Hides the line. Also affects RGLink.rgCalcedVisibility.
forDisplayOnly	boolean	Automatically true when from === to; otherwise false	Display-only line that does not participate in some relationship analysis or force-layout relationships. Self-loops are automatically display-only lines.
force_elastic	number	Unset	Line elasticity parameter in force layouts. Exact behavior depends on the active layout implementation.

Historical compatibility:

• isShow is deprecated. If hidden is unset, the source code sets hidden = !isShow.
• isHide is deprecated. If hidden is unset, the source code sets hidden = isHide.
• New code should use only hidden.

3. RGLine Runtime Fields

RGLine inherits JsonLine and adds runtime fields:

Field	Type	Description
id	string	Always exists at runtime. It is generated by add APIs when not provided.
isReverse	boolean	Internal calculated field indicating whether rendering direction is reversed. It mainly affects arrows, intersections, and endpoint offsets. Do not persist it manually.

A normal line does not directly contain endpoint node objects. To access endpoint nodes and multi-line indexes, read the corresponding RGLink:

const line = graphInstance.getLineById('line-a-b');
const link = graphInstance.getLinkByLineId('line-a-b');

console.log(link?.fromNode, link?.toNode);

4. Create, Query, Update, Delete Lines

Create Lines

graphInstance.addLines([
  {
    id: 'line-a-b',
    from: 'a',
    to: 'b',
    text: 'depends on'
  }
]);

graphInstance.addLines([
  {
    id: 'line-b-c',
    from: 'b',
    to: 'c',
    lineShape: RGLineShape.StandardOrthogonal
  }
]);

When adding normal lines:

• from/to must resolve to existing nodes.
• A duplicated id is skipped and a warning is printed.
• If isFakeLine: true, addLines dispatches it into addFakeLines.

Query Lines

const line = graphInstance.getLineById('line-a-b');
const lines = graphInstance.getLines();
const checkedLine = graphInstance.getCheckedLine();
const link = graphInstance.getLinkByLineId('line-a-b');

Update Lines

graphInstance.updateLine('line-a-b', {
  text: 'Updated relationship',
  color: '#2563eb',
  lineWidth: 3,
  dashType: 2
});

graphInstance.updateLineData('line-a-b', {
  weight: 0.8,
  status: 'active'
});

Update rules:

• updateLine(id, partial) shallow-merges fields.
• Prefer updateLineData for business-data updates.
• Changing from/to is a structural relationship change. It is recommended to delete the old line and add a new one to avoid temporary inconsistency in existing RGLink context.

Delete Lines

graphInstance.removeLineById('line-a-b');

graphInstance.removeLineByIds(['line-b-c', 'line-c-d']);

const line = graphInstance.getLineById('line-x-y');
if (line) {
  graphInstance.removeLine(line);
}

5. Multiple Lines And multiLineDistance

You can create multiple lines between the same two nodes:

graphInstance.addLines([
  { id: 'ab-1', from: 'a', to: 'b', text: 'Primary link' },
  { id: 'ab-2', from: 'a', to: 'b', text: 'Backup link' },
  { id: 'ab-3', from: 'a', to: 'b', text: 'Monitoring link' }
]);

At runtime, RGLink provides:

• totalLinesBetweenNodes: total number of lines between the same node pair.
• currentLineIndex: index of the current line among those lines.

Path generation uses options.multiLineDistance (default 30) to separate multiple lines and avoid complete overlap.

6. Recommended Style

const line = {
  id: 'api-to-db',
  from: 'api',
  to: 'database',
  text: 'SQL query',
  type: 'request',
  lineShape: RGLineShape.StandardOrthogonal,
  fromJunctionPoint: RGJunctionPoint.right,
  toJunctionPoint: RGJunctionPoint.left,
  color: '#2563eb',
  lineWidth: 2,
  showEndArrow: true,
  placeText: 'center',
  data: {
    protocol: 'postgres',
    p95: 38
  }
};

Recommended principles:

• Use from/to for structural relationships.
• Use text for displayed text.
• Put business attributes in data.
• Put core visual semantics in color/lineWidth/lineShape; do not keep them only in CSS.
• Combine type and the #line slot for complex line templates.

7. FAQ

Why Is The Line Not Displayed?

Common causes:

• The nodes referenced by from/to do not exist.
• The line has hidden: true.
• The start or end node is hidden, so RGLink.rgCalcedVisibility is false.
• A custom FakeLine target cannot resolve geometry.
• In performance mode or EasyView state, the main SVG layer may be replaced by simplified drawing.

Why Does lineShape Not Look Different?

When two nodes are very close, node sizes are large, or junction points are forced, some curve/polyline differences may be subtle. Try adjusting:

• fromJunctionPoint/toJunctionPoint
• junctionOffset
• lineRadius
• multiLineDistance
• textOffsetX/textOffsetY

Why Does MiniView Not Reflect My Custom CSS?

MiniView mainly reads line data fields such as color and lineWidth. If you only change .rg-line stroke in CSS, MiniView cannot know about that change.

8. Next

• Node Data Model
• FakeLine And Targets
• Link Runtime Object
• Graph Options
• Custom Line Slot