Build1 publisher2 min readPublished
Mermaid 12 draws its new use case diagrams with ELK and the neo look by default
Mermaid 12.0.0 adds UML use case diagrams that default to the redux-color theme, the neo look and ELK layout in place of Dagre. Theme and look can be reset for that type alone, while a page-wide layout: 'dagre' applies to every diagram.
The Engineer · Build desk
What happened
- Diagrams open with the single-token keyword usecase-beta, and every statement has to sit on its own physical line.
- Mermaid's docs say anything a user sets beats these defaults, and naming the previous theme and look in a diagram's front matter draws it the old way.
- Identifiers share one diagram-wide namespace across actors, use cases, boundaries, JSON nodes and explicit edges.
- An endpoint that is never declared becomes an ellipse use case, and actors appear only where an actor declaration names them.
- When an icon is unavailable, Mermaid draws its standard unknown-icon fallback and the diagram still renders.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- constraint A site that restores Dagre for use case diagrams through mermaid.initialize() also puts every other diagram on the page on Dagre, whatever that type's own Mermaid 12 default is.
- decision Teams adopting the type must either accept a mixed appearance on pages that also hold older diagram types, or pin theme 'default', look 'classic' and layout 'dagre' in config or front matter.
- exposure A misspelled or undeclared actor still renders, as an extra ellipse, so a docs pipeline that only checks for render errors will publish the wrong diagram.
Front matter restores the old drawing one diagram at a time [5]. Most sites will set it once, page-wide, and the docs print that form [7]:
```js mermaid.initialize({ layout: 'dagre', usecase: { theme: 'default', look: 'classic' } }) ```
Look at the nesting. `theme` and `look` sit under `usecase`, so they reach use case diagrams and nothing else [7]. `layout` sits at the top level, and the docs say it applies to every diagram [7]. Put all three keys at the top level and the old appearance comes back for every diagram on the page [6].
The split matters because Mermaid 12 resolves defaults per diagram type. The use case page says not every type uses redux-color, neo and ELK. It sends readers to a separate Per-diagram defaults section for the list and for the order in which Mermaid decides [4]. That section is not on the use case page, so the page alone does not establish which other types now default to ELK. If any do, a page-wide `layout: 'dagre'` sends them back to Dagre as well [7]. Front matter avoids that. The cost is adding it to every use case diagram source [5].
The documentation handles the change well. It draws the same diagram twice, once with the new defaults and once with the previous appearance [15]. It also spends a paragraph settling whether use case is one word or two [16].
The parser is lenient in two places, and both should be tested. First, declaration order never changes what a node resolves to. A relationship can name an endpoint before its declaration, and the kind, shape and label come out the same [12]. Second, undeclared endpoints default to ellipses. A misspelled actor name therefore produces a new ellipse use case beside the real, declared actor [11].
Identifiers follow `[A-Za-z0-9_]+`, so `1mg` and `3rd` are valid [8]. A quoted declaration gets its identifier by replacing each non-word character with an underscore, so "Reset password" resolves to Reset_password [1]. The docs recommend an explicit identifier wherever other statements need a readable, stable reference [10]. Stereotypes create no CSS classes or automatic selectors, so styling them takes classes or direct styles [14].
What to watch
- The Per-diagram defaults section: which other diagram types Mermaid 12 moved to redux-color, neo and ELK decides how far a page-wide layout: 'dagre' reaches.
- Whether Mermaid adds a per-type layout key alongside the usecase theme and look keys in mermaid.initialize().
- Whether a later release renames the usecase-beta keyword, since every existing diagram source names it directly.