Use labels to name relationships, separate repeated relationships into lanes, and mark crossings that are not connections. The example below renders editable labels, three parallel links, two nested self-loops, and crossing wires with jump-overs. Selecting a node emphasizes its connections without changing the document.
Start in the project left by your JavaScript, Angular, Qwik, React, or Vue quick start. Keep its entry point, configuration, and stylesheet imports. The packages installed there cover these samples; no additional install is needed.
1. Place editable labels
Specs express your data; the mounted diagram owns the live models. Type the data with NodeSpec and EdgeSpec. Give an edge a label to put text on its path. labelPlacement and labelStyle control where and how that text appears.
Add the following shared module in each framework's project. The first relationship has a label on the wire; the second places its label above the wire, with its own color and font size.
tsimport type { EdgeSpec, NodeSpec } from '@grafloria/renderer';
export const labelNodes: NodeSpec[] = [
{ id: 'api', label: 'API', selected: true,
position: { x: 60, y: 70 }, size: { width: 130, height: 60 } },
{ id: 'queue', label: 'Queue',
position: { x: 340, y: 70 }, size: { width: 130, height: 60 } },
{ id: 'worker', label: 'Worker',
position: { x: 620, y: 70 }, size: { width: 130, height: 60 } },
];
export const labelEdges: EdgeSpec[] = [
{ id: 'enqueue', source: 'api', target: 'queue', type: 'direct',
label: 'enqueues' },
{ id: 'consume', source: 'queue', target: 'worker', type: 'direct',
label: 'consumed by', labelPlacement: 'above',
labelStyle: { color: '#5f6b7a', fontSize: 11 } },
];
When mounted in step 5, drag a node: its label follows the rerouted edge. Drag the positioned “consumed by” label to reposition it; its position stays in the model. Dragging the metadata-only “enqueues” label selects its edge instead. Double-click the label to edit it in place. The JavaScript, React, Vue, and Qwik mounts below enable interaction.enableInPlaceTextEdit; Angular's canvas already handles double-clicking edge labels.
labelPlacement value | Result |
|---|---|
'on' | Text on the line, on its own small box; the default. |
'above' | Text above the line, without a background box by default. |
'below' | Text below the line, without a background box by default. |
For above/below placement, a horizontal run gives the label a readable slot. You can override its background with labelStyle. See the Edge labels demo for label dragging and re-anchoring.
2. Distinguish parallel links and self-loops
Add three edges with the same endpoints: parallel separation is on by default. The mounts in step 5 change the lane spacing to 24 pixels so the three relationships stay distinguishable.
For a self-loop, use the same node id for source and target. Put a SelfLoopConfig in style.selfLoop to control its geometry. These two loops leave and return to the top of the Retry node, with the second loop farther out.
tsimport type { SelfLoopConfig } from '@grafloria/engine';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';
const loop: SelfLoopConfig = { size: 50, width: 70, spacing: 24, side: 'top' };
export const parallelNodes: NodeSpec[] = [
{ id: 'client', label: 'Client',
position: { x: 60, y: 260 }, size: { width: 130, height: 60 } },
{ id: 'server', label: 'Server',
position: { x: 340, y: 260 }, size: { width: 130, height: 60 } },
{ id: 'retry', label: 'Retry',
position: { x: 620, y: 260 }, size: { width: 130, height: 60 } },
];
export const parallelEdges: EdgeSpec[] = [
{ id: 'request', source: 'client', target: 'server', type: 'direct', label: 'request' },
{ id: 'ack', source: 'client', target: 'server', type: 'direct', label: 'ack' },
{ id: 'status', source: 'client', target: 'server', type: 'direct', label: 'status' },
{ id: 'retry-short', source: 'retry', target: 'retry', type: 'orthogonal',
sourceHandle: 'top', targetHandle: 'top', label: 'retry', style: { selfLoop: loop } },
{ id: 'retry-long', source: 'retry', target: 'retry', type: 'orthogonal',
sourceHandle: 'top', targetHandle: 'top', label: 'timeout', style: { selfLoop: loop } },
];
Each lane is a separate selectable edge. Moving an endpoint reroutes the bundle; moving Retry moves its loops. Self-loops remain loops even if you turn off parallel separation. Compare the Parallel links & self-loops demo.
| Option | Type | Default | What it does |
|---|---|---|---|
rendererConfig.parallelLinks | boolean | true | Fans links between the same node pair into lanes. For render(), use renderer.parallelLinks. |
rendererConfig.parallelSpacing | number | 16 | Distance between adjacent lanes, in pixels. For render(), use renderer.parallelSpacing. |
style.selfLoop.size | number | 40 | Distance the loop bulges away from its node, in pixels. |
style.selfLoop.width | number | size | Lateral span used to spread nearby attachment points along the node's side. |
style.selfLoop.spacing | number | 18 | Extra size per additional loop on the same node. |
style.selfLoop.side | 'auto' | 'top' | 'right' | 'bottom' | 'left' | 'auto' | Uses the source port's side, or forces the named side. |
3. Render crossing jump-overs
Add two diagonal edges that form an X. Enable style.jumpPoints on both edges with a typed JumpPointConfig. The sample uses the shipped arc style; a crossing reads as two wires passing over each other, not a connection.
tsimport type { JumpPointConfig } from '@grafloria/engine';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';
const jumps: JumpPointConfig = { enabled: true, size: 12, style: 'arc' };
export const crossingNodes: NodeSpec[] = [
{ id: 'a', label: 'A', position: { x: 80, y: 440 }, size: { width: 100, height: 44 } },
{ id: 'b', label: 'B', position: { x: 80, y: 600 }, size: { width: 100, height: 44 } },
{ id: 'c', label: 'C', position: { x: 620, y: 440 }, size: { width: 100, height: 44 } },
{ id: 'd', label: 'D', position: { x: 620, y: 600 }, size: { width: 100, height: 44 } },
];
export const crossingEdges: EdgeSpec[] = [
{ id: 'ad', source: 'a', target: 'd', type: 'direct', style: { jumpPoints: jumps } },
{ id: 'bc', source: 'b', target: 'c', type: 'direct', style: { jumpPoints: jumps } },
];
Moving a node moves the crossing and its jump. Separating the wires removes the jump. The Jump-overs demo shows both states.
| Option | Type | Default | What it does |
|---|---|---|---|
enabled | boolean | Required | Enables jump rendering for this edge. |
size | number | 10 | Jump size in pixels; zero leaves the path unchanged. |
style | 'arc' | 'gap' | 'bridge' | 'arc' | Draws a curved hop, a break in the line, or an angular bridge. |
detectMode | 'all' | 'perpendicular' | 'threshold' | 'all' | Filters crossings by their angle. |
threshold | number | 45 | Minimum angle in degrees in 'threshold' mode. |
'all' includes every detected crossing. 'perpendicular' includes crossings at an acute angle of at least 75 degrees; it does not use threshold. 'threshold' includes angles at least as large as threshold.
Use straight-segment paths for this example. A two-point smooth or bezier curve does not participate in jump detection. Edges that merely touch at a path endpoint do not get a jump there.
4. Highlight the selected node's connections
Combine the three sets of specs. The API node starts selected, so its two-step downstream path appears emphasized immediately. Selecting Client instead emphasizes its three relationships while the other lines fade.
HighlightConnectedOptions controls this selection-derived view. On a mounted DiagramInstance, call setHighlightConnected() to change it live. The shared initializer returns getHighlightConnected() so you can inspect the applied setting.
tsimport type { DiagramInstance, EdgeSpec, HighlightConnectedOptions, NodeSpec } from '@grafloria/renderer';
import { labelNodes, labelEdges } from './edge-labels';
import { parallelNodes, parallelEdges } from './parallel-edges';
import { crossingNodes, crossingEdges } from './crossing-edges';
export const nodes: NodeSpec[] = [...labelNodes, ...parallelNodes, ...crossingNodes];
export const edges: EdgeSpec[] = [...labelEdges, ...parallelEdges, ...crossingEdges];
export const highlight: HighlightConnectedOptions = {
depth: 2,
stroke: '#dc2626',
strokeWidth: 3,
outgoing: 'dashed',
dimOpacity: 0.25,
};
export function configureConnections(instance: DiagramInstance): boolean | HighlightConnectedOptions {
instance.setHighlightConnected(highlight);
return instance.getHighlightConnected();
}
The initializer schedules its own repaint. Do not add a redraw call. Highlighting is view state: it adds no undo step, does not sync to collaborators, and is absent from exports. An edge selected directly keeps its selection appearance. See the Highlight connected lines demo for direct-neighbor and whole-path tracing.
| Option | Type | Default | What it does |
|---|---|---|---|
depth | number | 1 | 1 marks touching lines; 2 reaches one node farther upstream and downstream; Infinity traces every path in and out. |
stroke | string | Theme's primary text color | Highlighted line color. |
strokeWidth | number | 2.5 | Highlighted line width. |
outgoing | 'solid' | 'dashed' | 'solid' | Keeps outgoing lines solid, or dashes them as a direction cue. |
dimOpacity | number | 0.4 | Opacity of unrelated lines while a node is selected; 1 leaves them unfaded. |
Pass true for the built-in highlight defaults, an options object to customize them, or false to turn highlighting off. getHighlightConnected() returns that current boolean or options object, not the current selection. A highlighted line crossing another node is lifted above it and dashed regardless of outgoing.
Connection highlighting and node outlines
Keep highlightConnected distinct from highlighterConfig: the former emphasizes connected lines; the latter controls the extra outline layer for hovered nodes, selected nodes, validation issues, and valid connection targets. Use Angular's [highlighterConfig]="false" to remove that entire layer without removing the selected node's own border, resize handles, or toolbar. Pass an object such as { showHover: false } to suppress only hover outlines. Each object starts from the defaults, not the previous configuration.
React's highlighterConfig prop and Vue's highlighter-config prop control the same outline layer. It is off by default in React and Vue and on by default in Angular. Pass true to enable all kinds, false to disable them, or { showValidation: false } to keep the other outlines without validation outlines. Changing the prop takes effect without remounting; on a mounted JavaScript instance, setHighlighterConfig() changes the layer live.
5. Mount the example
The mounts below add label editing, 24-pixel parallel spacing, and connection highlighting through render, React's GrafloriaFlow, Vue's GrafloriaFlow, Qwik's GrafloriaFlow, or Angular's DiagramCanvasComponent; see Edit nodes for mounting and state ownership.
Add the framework component below, then render it from the quick start's existing root component. For JavaScript, update the quick start's src/main.ts as shown. For Qwik, place the four shared modules from steps 1–4 in src/routes/readable-edges/ instead of src/, add the route below alongside them, and open /readable-edges/. Leave the framework's mounting entry and application configuration intact.
tsimport './style.css';
import { render } from '@grafloria/element';
import { nodes, edges, configureConnections } from './readable-edges';
const app = document.querySelector<HTMLDivElement>('#app');
if (!app) throw new Error('Missing #app');
app.innerHTML = '<div id="canvas" style="width:100%;height:720px"></div>';
const instance = render({ nodes, edges }, '#canvas', {
renderer: { parallelSpacing: 24 },
interaction: { enableInPlaceTextEdit: true },
});
console.log('Connection highlight setting', configureConnections(instance));
tsimport { Component, signal } from '@angular/core';
import { DiagramCanvasComponent } from '@grafloria/angular';
import type { EdgeSpec, NodeSpec } from '@grafloria/renderer';
import { nodes, edges, highlight } from '../readable-edges';
@Component({
selector: 'app-readable-edges',
imports: [DiagramCanvasComponent],
template: `
<grafloria-diagram-canvas
[(nodes)]="nodes" [(edges)]="edges"
[rendererConfig]="rendererConfig"
style="display:block;width:100%;height:720px" />
`,
})
export class ReadableEdgesComponent {
readonly nodes = signal<NodeSpec[]>(nodes);
readonly edges = signal<EdgeSpec[]>(edges);
readonly rendererConfig = { parallelSpacing: 24, highlightConnected: highlight };
}
tsximport { component$ } from '@builder.io/qwik';
import { GrafloriaFlow } from '@grafloria/qwik';
import { nodes, edges, highlight, configureConnections } from './readable-edges';
export default component$(() => (
<div style={{ width: '100%', height: '720px' }}>
<GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
highlightConnected={highlight}
rendererConfig={{ parallelSpacing: 24 }}
interaction={{ enableInPlaceTextEdit: true }}
onInit$={(instance) => {
console.log('Connection highlight setting', configureConnections(instance));
}} />
</div>
));
tsximport { GrafloriaFlow } from '@grafloria/react';
import { nodes, edges, configureConnections } from './readable-edges';
export function ReadableEdges() {
return (
<div style={{ width: '100%', height: '720px' }}>
<GrafloriaFlow defaultNodes={nodes} defaultEdges={edges}
rendererConfig={{ parallelSpacing: 24 }}
interaction={{ enableInPlaceTextEdit: true }}
onInit={(instance) => {
console.log('Connection highlight setting', configureConnections(instance));
}} />
</div>
);
}
vue<script setup lang="ts"> import { GrafloriaFlow } from '@grafloria/vue'; import type { DiagramInstance } from '@grafloria/renderer'; import { nodes, edges, configureConnections } from './readable-edges'; function onInit(instance: DiagramInstance): void { console.log('Connection highlight setting', configureConnections(instance)); } </script> <template> <div style="width:100%;height:720px"> <GrafloriaFlow :default-nodes="nodes" :default-edges="edges" :renderer-config="{ parallelSpacing: 24 }" :interaction="{ enableInPlaceTextEdit: true }" @init="onInit" /> </div> </template>
Angular passes highlightConnected through rendererConfig; its ready instance exposes a narrower API than DiagramInstance. React and Vue apply the setting in their initialization callback. Qwik also passes highlightConnected as a prop so the binding's live synchronization retains the same setting. It uses a $ callback prop and keeps no live instance in resumable state. Each binding owns cleanup when its component unmounts.
You now have labeled relationships along the top, a three-lane bundle and nested Retry loops in the middle, and an X with jump-overs below. API's connections start red and dashed; unrelated lines start faded. Press another node to move the highlight to its connections.
Pitfalls and related tasks
- Reserve room around self-loops: their
sizeextends beyond the node body, and each additional loop addsspacing. - Enable in-place text editing on the non-Angular mounts before expecting double-click to open an editor.
- Use an explicit container height. For nested hosts, see Nest containers and lanes.
- For routes, pinned anchors, and saved bends, continue with Route and edit edges.
- To keep edited labels and their positions, save the document rather than a projection of the specs; see Save and restore documents.
Was this page helpful?