elkjs-layout

---
name: elkjs-layout
description: "ELK.js graph layout configuration with working code examples. Use this skill BEFORE writing any ELK.js code — it contains the exact configurations, patterns, and edge routing extraction that were proven to work. Triggers when: code imports 'elkjs', you're configuring ELK layout options, building a graph visualization pipeline, working with React Flow + ELK, or the user mentions 'ELK', 'elkjs', 'graph layout', 'node positioning', 'edge routing', or 'layout algorithm'. ELK.js is a training data blind spot for ALL LLMs — do NOT guess at options. Use the examples in this skill instead."
---

# ELK.js Layout — Working Configurations and Code

ELK.js has 400+ layout options and near-zero representation in AI training data. Do NOT guess at configuration. Use the working examples below — they were proven through iterative development and agentic research.

## Quick Reference: The Config That Works

```typescript
layoutOptions: {
  "elk.algorithm": "layered",
  "elk.direction": "RIGHT",
  "elk.layered.spacing.baseValue": "100",
  "elk.padding": "[left=50, top=50, right=50, bottom=50]",
  "elk.edgeRouting": "ORTHOGONAL",
  "elk.layered.nodePlacement.strategy": "NETWORK_SIMPLEX",
}
```

### Why Each Option Matters

| Option | What It Does | Why This Value |
|--------|-------------|----------------|
| `baseValue: "100"` | Sets a single default for ALL spacing options at once | Produces uniform spacing without setting 15 individual parameters |
| `NETWORK_SIMPLEX` | Node placement strategy | More uniform spacing than BRANDES_KOEPF (default), optimizes globally |
| `ORTHOGONAL` | Edge routing mode | Computes 90-degree bend points that route around nodes — edges never cross through nodes |
| `padding` | Space between graph boundary and outermost nodes | Breathing room at graph edges |

### What NOT to Do

- **Don't set `nodeNode` and `nodeNodeBetweenLayers` separately** — use `baseValue` instead for uniform spacing
- **Don't use BRANDES_KOEPF** with `fixedAlignment: 'BALANCED'` — NETWORK_SIMPLEX produces better results with less configuration
- **Don't discard ELK's edge routing data** — the `sections` array in edge results contains node-avoiding paths
- **Don't guess at option names** — they use Java-style naming (`org.eclipse.elk.layered.nodePlacement.strategy`) and the short forms sometimes don't match

## Working Code Examples

### Full Pipeline: Agent Output → ELK Layout → React Flow

See `examples/transform-pipeline.ts` — a complete working transformation pipeline that:
1. Reads agent output JSON
2. Computes node dimensions from text content
3. Runs ELK with the proven config
4. Extracts edge routing paths as SVG
5. Outputs React Flow-ready JSON

### Custom Edge Component: Rendering ELK Paths

See `examples/elk-routed-edge.tsx` — a React Flow custom edge that:
1. Renders ELK's computed SVG path as a static dashed line
2. Animates particles along the path to show flow direction
3. Never crosses through nodes (because ELK computed the path to avoid them)

### Edge Path Extraction

See `examples/extract-edge-paths.ts` — how to convert ELK's edge `sections` data into SVG path strings.

## Key Concepts

### Spacing

`baseValue` is the master control. It sets the default for ALL spacing options:
- `nodeNode` (vertical gap between nodes in same layer)
- `nodeNodeBetweenLayers` (horizontal gap between layers)
- `edgeNode`, `edgeEdge`, and all others

If you explicitly set any individual option, it overrides `baseValue` for that option only.

### Edge Routing

ELK returns edge routes in `edge.sections`:
```typescript
edge.sections[0] = {
  startPoint: { x, y },
  bendPoints: [{ x, y }, { x, y }, ...],  // 90-degree bends that avoid nodes
  endPoint: { x, y }
}
```

Convert to SVG path: `M startX startY L bend1X bend1Y L bend2X bend2Y ... L endX endY`

**Critical: You must extract and use this data.** If you let React Flow compute its own edge paths (default, smoothstep, bezier), they will NOT avoid nodes.

### fitView Scaling

ELK outputs absolute pixel positions on a reference canvas. React Flow's `fitView` scales these to the actual viewport. This means:
- The layout algorithm produces clean relative positions
- `fitView` maps them to whatever space is available
- Relative spacing and non-intersection are preserved through scaling
- `fitView` should run on each layer's visible subgraph (not the full graph) for optimal per-layer composition

## When to Research Further

If you need options beyond what's documented here — compound nodes, port constraints, edge bundling, wrapping — dispatch `/niche-library-research` targeting:
- https://eclipse.dev/elk/reference/options.html
- https://github.com/kieler/elkjs/issues
- https://eclipse.dev/elk/documentation/tooldevelopers/graphdatastructure/spacingdocumentation.html