ELK.js Layout: Build Advanced Automatic Graph Layouts

ELK.js (Eclipse Layout Kernel) is a powerful graph-layout library for building complex, structured, and automatically arranged diagrams in React Flow. It offers extensive configuration options, making it an excellent choice for applications that require precise control over node positioning, edge routing, spacing, and graph direction.

Unlike simpler layout libraries, ELK.js provides a wide range of algorithms and configuration properties for handling complex graph structures. It is particularly useful for workflow editors, node-based applications, architecture diagrams, and large interactive visualizations.

What Is ELK.js?

ELK.js is the JavaScript implementation of the Eclipse Layout Kernel, a graph-layout engine originally developed in Java. It helps automatically calculate the positions of nodes and the routing of edges based on a graph's structure and configuration.

With ELK.js, you can create layouts such as:

• Hierarchical layouts: Arrange nodes into structured levels.
• Directed graph layouts: Position nodes according to connection direction.
• Complex workflow layouts: Organize large workflows with multiple branches.
• Custom graph layouts: Configure spacing, alignment, routing, and direction.

Its flexibility makes ELK.js a strong option when basic automatic layout libraries cannot meet your application's requirements.

Why Use ELK.js with React Flow?

React Flow provides the interactive canvas for building node-based applications, while ELK.js handles the automatic graph layout calculations.

Combining these libraries allows you to:

• Automatically position nodes based on their relationships.
• Control graph direction, including left-to-right and top-to-bottom layouts.
• Configure node spacing and layer distances.
• Generate more organized layouts for complex workflows.
• Improve the readability of large diagrams.

However, ELK.js is more complex to configure than alternatives such as Dagre. Its extensive options provide greater flexibility but require additional implementation and testing.

Installing ELK.js

Install ELK.js using npm:

npm install elkjs

Import the library into your React Flow application:

import ELK from 'elkjs/lib/elk.bundled.js';

const elk = new ELK();

Creating an Automatic Layout

ELK.js calculates node positions asynchronously. You can pass your React Flow nodes and edges into an ELK graph, calculate the layout, and then update the node positions.

Here is a simplified example:

const elkGraph = {
  id: 'root',
  layoutOptions: {
    'elk.algorithm': 'layered',
    'elk.direction': 'RIGHT',
    'elk.spacing.nodeNode': '50',
    'elk.layered.spacing.nodeNodeBetweenLayers': '80',
  },
  children: nodes.map((node) => ({
    id: node.id,
    width: 180,
    height: 60,
  })),
  edges: edges.map((edge) => ({
    id: edge.id,
    sources: [edge.source],
    targets: [edge.target],
  })),
};

const layoutedGraph = await elk.layout(elkGraph);

The returned graph contains calculated positions that can be mapped back to React Flow nodes.

Using an Asynchronous Layout Hook

Because ELK.js performs layout calculations asynchronously, a custom React hook such as useLayoutedElements can help manage the process.

A typical implementation should:

1. Read the current nodes and edges.
2. Convert them into an ELK-compatible graph.
3. Run the asynchronous layout calculation.
4. Map the calculated coordinates back to React Flow nodes.
5. Update the canvas with the new positions.

This approach keeps layout logic separate from the main React Flow component and makes it easier to support different layout configurations.

ELK.js Configuration Options

One of ELK.js's biggest advantages is its extensive configuration system. You can customize the layout algorithm, graph direction, node spacing, edge routing, and many other properties.

For example:

const layoutOptions = {
  'elk.algorithm': 'layered',
  'elk.direction': 'DOWN',
  'elk.spacing.nodeNode': '40',
  'elk.layered.spacing.nodeNodeBetweenLayers': '70',
  'elk.edgeRouting': 'ORTHOGONAL',
};

These options allow you to build layouts that match the structure and visual requirements of your application.

When Should You Use ELK.js?

ELK.js is especially useful when building applications that need advanced graph organization and precise layout control.

Consider using it for:

• Complex workflow and automation builders.
• Software architecture and dependency diagrams.
• Large node-based editors.
• Data pipelines and process visualization.
• Diagrams with advanced edge-routing requirements.

For simpler diagrams, Dagre may be easier to implement. But when you need more control over graph layout behavior, ELK.js is worth exploring.

ELK.js Documentation and Resources

ELK.js has a large configuration API, so its official documentation is an important resource when implementing advanced layouts.

• ELK.js GitHub Repository
• Eclipse ELK Reference Documentation