Graph

The Graph component (ui:graph) renders node-and-edge diagrams with automatic layout powered by D3 and Dagre. It supports directed acyclic graphs, flowcharts, mind maps, and force-directed layouts. Nodes and edges can carry labels, semantic types, groups, and custom style overrides.

Examples

View Glyph Markdown source

```ui:graph
type: dag
nodes:
  - id: api
    label: API Gateway
    type: service
  - id: auth
    label: Auth Service
    type: service
  - id: db
    label: PostgreSQL
    type: database
  - id: cache
    label: Redis Cache
    type: database
edges:
  - from: api
    to: auth
    label: authenticates
  - from: api
    to: cache
    label: reads
  - from: auth
    to: db
    label: queries
layout: top-down
```

Mind map example

View Glyph Markdown source

```ui:graph
type: mindmap
nodes:
  - id: root
    label: Glyph JS
  - id: parser
    label: Parser
  - id: compiler
    label: Compiler
  - id: runtime
    label: Runtime
  - id: schemas
    label: Schemas
edges:
  - from: root
    to: parser
  - from: root
    to: compiler
  - from: root
    to: runtime
  - from: root
    to: schemas
```

Properties

Property	Type	Required	Default	Description
`type`	`"dag" \| "flowchart" \| "mindmap" \| "force"`	Yes	—	The graph variant that determines default layout and visual style.
`nodes`	`Node[]`	Yes	—	An array of node objects to render.
`edges`	`Edge[]`	Yes	—	An array of edge objects connecting nodes.
`layout`	`"top-down" \| "left-right" \| "bottom-up" \| "radial" \| "force"`	No	Determined by `type`	Override the automatic layout direction.
`interactionMode`	`"modifier-key" \| "click-to-activate" \| "always"`	No	`"modifier-key"`	Controls how users can zoom and pan the graph.

Node object

Property	Type	Required	Default	Description
`id`	`string`	Yes	—	Unique identifier for the node. Referenced by edges.
`label`	`string`	Yes	—	Display text rendered inside the node.
`type`	`string`	No	—	Semantic type (e.g. “service”, “database”). Used for styling and grouping.
`style`	`Record<string, string>`	No	—	CSS-like style overrides applied to the node element.
`group`	`string`	No	—	Grouping key. Nodes with the same group are visually clustered.

Edge object

Property	Type	Required	Default	Description
`from`	`string`	Yes	—	The `id` of the source node.
`to`	`string`	Yes	—	The `id` of the target node.
`label`	`string`	No	—	Text displayed on the edge.
`type`	`string`	No	—	Semantic type (e.g. “depends-on”, “calls”). Used for styling.
`style`	`Record<string, string>`	No	—	CSS-like style overrides applied to the edge path.

Graph types

dag — Directed acyclic graph. Best for dependency trees, build pipelines, and data flow diagrams. Default layout: top-down.
flowchart — Process flow with decision points. Default layout: top-down.
mindmap — Radial tree emanating from a central node. Default layout: radial.
force — Force-directed layout where nodes repel and edges attract. Best for loosely structured networks.

Layout options

The layout property overrides the default layout direction for the chosen graph type:

Layout	Description
`top-down`	Root nodes at the top, children below.
`left-right`	Root nodes on the left, children to the right.
`bottom-up`	Root nodes at the bottom, children above.
`radial`	Nodes arranged in concentric circles from the center.
`force`	Physics-based simulation with no fixed direction.

Interaction Modes

The interactionMode property controls how users can zoom and pan the graph. Three modes are available:

Modifier Key (Default)

Requires holding Ctrl (Windows/Linux) or ⌘ Cmd (Mac) while scrolling to zoom. Panning via click-and-drag always works.

type: dag
interactionMode: modifier-key
nodes:
  - id: a
    label: Node A
  - id: b
    label: Node B
edges:
  - from: a
    to: b

When to use: Documentation, blogs, or any scrollable content where accidental zooming would disrupt reading.

Behavior:

Scroll: Page scrolls normally (tooltip appears on first attempt)
Ctrl/Cmd + Scroll: Zooms in/out
Click and drag: Pans the graph

Click to Activate

Requires clicking the graph once to activate zoom/pan controls. Press Escape or click outside to deactivate.

type: dag
interactionMode: click-to-activate
nodes:
  - id: a
    label: Node A
  - id: b
    label: Node B
edges:
  - from: a
    to: b

When to use: Dense dashboards or galleries where you want explicit opt-in for interaction.

Behavior:

Initial state: Graph shows “Click to interact” overlay
Click graph: Activates zoom/pan
Scroll (active): Zooms in/out
Drag (active): Pans the graph
Escape / click outside: Deactivates

Always

Traditional behavior with no restrictions. Scrolling immediately zooms.

type: dag
interactionMode: always
nodes:
  - id: a
    label: Node A
  - id: b
    label: Node B
edges:
  - from: a
    to: b

When to use: Standalone visualization apps or when zoom-first interaction is desired.

Behavior:

Scroll: Zooms in/out immediately
Click and drag: Pans the graph

Shared abstraction with Relation

The Graph and Relation components share a unified relational abstraction. Both use nodes and edges, but ui:relation constrains the model by requiring cardinality on edges and treating nodes as entities with typed attributes.

Interaction events

When interactive: true is set, the graph emits a graph-node-click event when the user clicks any node.

```ui:graph
interactive: true
type: dag
nodes:
  - id: api
    label: API Gateway
  - id: db
    label: Database
edges:
  - from: api
    to: db
```

Event kind: graph-node-click

Payload field	Type	Description
`nodeId`	`string`	The `id` of the clicked node.
`nodeLabel`	`string`	The display label of the clicked node.

Accessibility

The graph is rendered inside an SVG with role="img" and a descriptive aria-label summarizing the graph structure.
Each node is focusable via keyboard and exposes its label through aria-label.
Edge relationships are described in a visually hidden text summary for screen readers.
The prefers-reduced-motion media query disables layout animations when the user has requested reduced motion.