Overview

D2 supports using a variety of different layout engines. The choice of layout engines can significantly influence your overall diagram. Each layout also has varying degrees of support for certain keywords. Though we try our best to keep things consistent, ultimately we have the most control over our custom-built layout engine and are limited by what the other layout engines support.

Layout engines

• dagre (default): A fast, directed graph layout engine that produces layered/hierarchical layouts. Based on Graphviz's DOT algorithm.
• ELK: Also a directed graph layout engine. More mature than dagre, better maintained (part-time academic research team working on it), with recent releases.
• TALA: New layout engine designed specifically for software architecture diagrams.

You can choose whichever layout engine you like and works best for the diagram you're making. Each one has its tradeoffs, visit the individual pages to learn more.

To see available layouts on your machine, you can run d2 layout. Each layout engine can also have specific configurable flags, which you can find by running d2 layout [engine], e.g. d2 layout dagre.

To specify the layout used, you can either set the flag --layout=dagre or set it as an environment variable, $D2_LAYOUT=dagre.

Layout-specific functionality

Some keywords and functionality are only available for certain layout engines. We authored and maintain TALA, so it is the only one we have full control over. We write shims for Dagre and ELK, but some things are fundamental to the layout engines, and the only way to support everything we want to do on those is to fork (which we may eventually do).

These are mentioned in other parts of the doc and aggregated here:

• near set to another object. near can be set to constants for all layout engines, but only TALA can use it to set to objects.
• width and height on containers. TALA will add this soon, but currently it is only in ELK. Note that these keywords work on non-containers in all layout engines.
• top and left to lock positions only work in TALA.
• Connections from ancestors to descendants (e.g. a container to its child) do not work in Dagre.

Direction

Set direction to one of the following to influence an explicit direction your diagram flows towards.

Options

• up
• down
• right
• left

Directions per container (TALA only)

info

Directions can only be set at a global level for all the layout engines except TALA. This is a limitation of their algorithms, which are hierarchical and only work in one direction. We are investigating ways to hack it to work.