Blog / Use cases
Ways a diagram can lie to your users
A wrong number in a table looks wrong. A wrong diagram looks fine — that's what makes it dangerous. Here are three lies we see diagram UIs tell in production, why they slip through code review, and why we ended up treating them as correctness bugs in the engine rather than styling problems in the app.
Lie #1 — three edges render as one
A classic from the support queues of every flow library: you declare three edges between the same two nodes and see one on screen. Nothing crashed. All three are there — drawn on exactly the same path, overlapping into a single line. Your user reads "one relationship" where the data says three.
The usual fix is manual: invent separate connection points, or write a custom edge that offsets its path. Our fix is that the renderer refuses to tell this lie — parallel edges fan apart, labels kept legible:
rendererConfig: { parallelLinks: true, parallelSpacing: 12 }
Lie #2 — the edge that might connect, or might pass behind
At six nodes a straight edge is fine. At sixty, edges slice through node bodies, and
every crossing is a question your user has to answer alone: does this line connect
to that box or pass behind it? We wrote a
whole deep-dive on the machinery, but the
principle fits in a sentence: links must never run through node bodies — so the
avoid router walks around them, keeps doing it live while you drag, and when
a user hand-bends a wire, the bend becomes a constraint the router respects instead of a
casualty it discards.
Lie #3 — the label near the wrong thing
State machines are the worst offenders: transition text that floats in ambiguous space between three arrows. Whose label is it? In Grafloria edge labels are anchored to their path, editable in place, and draggable — and a dragged label position persists in the model, so the disambiguation someone did by hand survives serialization, undo, and everyone else's session.
Why this is an engine's job
Every one of these can be patched in app code — teams do it every day, and the patches are where diagram UIs go to become unmaintainable. The reason we bake them into the engine is the same reason databases enforce constraints: a rule enforced at the bottom can't be forgotten at the top. Our demos all run in CI with real pointer events partly for this — a diagram that lies is a failing gate, not a screenshot in a bug report.
See it live: edge demos · the concepts: Edges & routing.