npm / mermaid
mermaid
What changed in mermaid 10 to 12, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-18.
24 breaking18 security1 deprecations52 new APIs and options2 performance28 behavior and defaults105 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli initmermaid 1272 changes
Breaking changes 15
The ELK option is enabled by default, routing edges that feed back into a subgraph downstream; set it to false to retain the previous routing.
Removed from Mermaid's public API; the layout internal exports are now bundled by @mermaid-js/layout-elk.
The CommonLayout* types are no longer part of Mermaid's public API.
Removed from Mermaid's public API; the layout internal exports are now bundled by @mermaid-js/layout-elk.
Removed from Mermaid's public API; the layout internal exports are now bundled by @mermaid-js/layout-elk.
The flowchart, class, and state config sections no longer support defaultRenderer; it is ignored. Use the top-level layout option to select the layout algorithm.
Legacy flowchart, class, and state diagram IDs are gone; detectType now returns flowchart-v2, classDiagram, and stateDiagram for that syntax.
This dist file now contains syntax es-module-lexer used by Vite rejects; Vite users should import the mermaid package specifier or core build instead.
Stadium, circle, diamond, double-circle, Display, and Delay labels no longer wrap at this width; explicit line breaks are kept, and an explicit node width takes precedence.
Edges now attach to non-rectangular shapes on their outlines rather than being displaced by half a pixel; rendered output can move by up to a pixel where polygon shapes terminate edges.
ELK is bundled, registered automatically, and is now the default layout for flowchart, state, class, entity-relationship, requirement, and use-case diagrams. Set layout: dagre to retain the previous layout.
ELK replaces dagre as the default layout. Set layout to dagre during initialization or in diagram front matter to retain the previous layout.
Hops keep a straight run clear of bends and are omitted if they would shrink below 60% of the requested radius. Crossings inside a rounded bend are ignored; affected swimlane and ELK diagrams may render differently.
Removed from Mermaid's public API; the layout internal exports are now bundled by @mermaid-js/layout-elk.
Mermaid now targets ES2024 and requires Safari 17.4+; package metadata declares Node.js v22.12+. Older browsers may need polyfills or transpilation.
New APIs and options 7
Opt-in mindmap coloring by hierarchy depth uses the existing theme palette.
Packet diagrams add bitOrder, defaulting to ascending; descending mirrors each row so it reads from highest bit to lowest.
A subgraph can select its own ELK algorithm with @{ algorithm: ... }; supported values include elk.layered, elk.box, elk.rectpacking, elk.stress, elk.force, elk.mrtree, elk.radial, and elk.sporeOverlap.
Layout engines can opt to measure plain cluster labels at their natural width rather than the flowchart.wrappingWidth fallback; bundled ELK uses this and labelled ELK subgraphs may change size.
theme, look, and layout can be configured per diagram type, including in initialize() or front matter; diagram-scoped values take precedence over global values at the same layer.
Adds UML use case diagrams with actors, use cases, system boundaries, relationships, stereotypes, notes, JSON tables, class and style support, accessibility metadata, and business variants.
Use case diagrams can choose a per-element palette cycle with colorScheme: 'rotate'; otherwise the redux themes colour elements by role, and classDef/style takes precedence.
Performance 1
detectType and extractFrontMatter use a linear scanner instead of a polynomially backtracking regex on hot paths.
Behavior and default changes 17
Error diagrams now show the actual parse error below the syntax-error headline, wrapped to at most four lines.
Gantt diagrams now warn when a task references an unknown after/until task ID or has an invalid end value.
Sequence diagrams now allow whitespace between an actor name and its @{ ... } configuration object.
Actor-menu keywords can be used as participant IDs in messages; the keywords are recognized as statements only when an actor follows on the same line.
Composite blocks now use per-container colours under redux-color and redux-dark-color; opt in with an explicit theme, and classDef/style still wins.
The default ELK preset now uses balanced Brandes-Koepf placement to improve branch and composite-state entry alignment; some diagrams may become wider or taller, while depthFirst retains the previous default.
Hand-drawn hachure fills are denser and read as an even tint rather than stripes; state markers are similarly close to solid.
ELK layouts and their listed variants work without installing or registering @mermaid-js/layout-elk; the tiny build omits ELK and falls back to dagre.
neo replaces classic as the default look for flowchart, class, state, ER, requirement, sequence, use case, swimlane, Venn, and agentflow diagrams.
The release introduces a redux-color / neo default appearance; existing flowcharts, state, and class diagrams may be recoloured, and config can specify theme: default and look: classic to keep the old look.
Class boxes and flowchart subgraph containers receive per-item palette colours, cycling every 12; explicit classDef or style still takes precedence.
Composite states receive per-container palette colours; nested composites advance through the palette, while explicitly styled composites opt out.
Swimlane lanes receive per-lane colours cycling every 12; the lane holding ungrouped nodes gets its own slot and follows the diagram look.
The theme now defines variables previously missing from its base theme, and pie, gantt, user-journey, and Venn diagrams use its palette.
Cycle removal starts from source nodes so feedback edges are reversed instead of forward-flow edges.
Swimlane layout is now supplied by its schema default rather than forced by its init hook, so per-diagram and front matter layout settings are honored.
redux-color replaces default as the default theme for flowchart, class, state, ER, requirement, sequence, use case, swimlane, Venn, and agentflow diagrams.
Fixes and other changes 32
Circle and double-circle nodes are sized from their label instead of
minNodeWidth, and neo circle padding is trimmed.Edges are clipped for the layout engine that drew them, so diagrams pinning their own engine still render when the configured default is another engine.
ELK no longer straightens an edge terminal when doing so would place a label over another edge or an edge through a label.
Mindmap HTML labels remain readable in the neo look on themes that repaint node backgrounds.
Mindmap node labels are centered when
htmlLabelsis false.Swimlane cluster DOM IDs are scoped like other cluster IDs, preventing collisions between two diagrams on one page.
Shared terminal lanes are split again after crossing cleanup, preventing a detouring edge from ending at the same attachment point as a neighboring edge.
Swimlane nodes with no edges keep their source order inside a lane instead of being sorted by ID.
In LR diagrams, a lane's title band is moved clear of an edge crossing it when lanes have no direction of their own and the edge runs along the band's border.
Cardinality labels are placed beside relation ends on dagre's sides with ELK, centered on dagre's ends, and no longer have clipped text.
ELK class-diagram cardinalities are kept off namespace frames.
Edge labels are re-projected onto the straightened route so they remain centered on the edge.
Duplicate event modeling frame IDs are rejected before rendering.
Explicit source relations are preserved on event modeling reset frames.
Repeated subgraph IDs render as one merged subgraph with ELK; classes and collapsed view apply regardless of declaration order.
Hyphenated actor and participant names are allowed when a configuration object is attached.
Partial overrides of object-valued theme variables retain theme-generated values for keys omitted from the override.
The xychart title is centered over the plot area rather than the whole chart.
Sequence diagram actor background and border palettes are indexed by their own lengths, preventing missing fills when palette lengths differ.
Block diagrams using look: neo now render node borders instead of losing them when gradient definitions were unavailable.
Labels now treat </br> as a line break in both plain SVG text and HTML-label rendering paths.
Bundling fastdom fixes issues with a global define.
Circle, double-circle, Delay, and Display nodes size themselves using label height as well as width so wrapped labels stay inside their outlines. Stacked and lined document labels clear the full depth of the wavy bottom edge.
Unregistered layouts now fall back to dagre with a warning instead of throwing; this also covers state diagrams and mindmaps.
Sequence diagram actors, notes, and participant alignment render correctly under the redux theme.
The theme now defines variables previously missing from its base theme, and pie, gantt, user-journey, and Venn diagrams use its palette for more distinguishable colors and banding.
redux-dark, redux-dark-color, and neo-dark now compute secondBkg correctly for railroad; their gantt done-task labels also meet improved contrast, and ER/requirement styles validate look before CSS selector interpolation.
C4 relationships, including BiRel and Rel_* forms, can now use boundary aliases as endpoints without throwing an unknown-shape error.
Block node borders now use the theme's strokeWidth instead of a fixed 1px, correcting themes such as neo that specify a different width.
C4 named attributes such as $tags and $sprite no longer get wrapped as text when they occupy a positional text slot after an omitted argument, preventing rendering crashes.
An unrecognized theme name now resolves to the default theme name as well as its variables, rather than retaining an invalid name.
Under ELK, ovals receive vertical padding and spread edge attachment points across their sides; the renderer accounts for end-marker offsets so short entry stubs do not flip markers.
mermaid 11155 changes
Breaking changes 9
classDiagram uses the unified (v2) renderer by default; set class.defaultRenderer to 'dagre-d3' to restore the legacy renderer.
This function is deprecated and has no observable effect because the next render() or parse() call clears currentConfig.
Class diagram namespaces now support nesting via dot notation and syntactic nesting; set this option to false to retain the previous non-nested rendering behavior.
Some CSS at-rules are disallowed in custom CSS.
In state diagrams, end note closes a note only when used on a new line.
Comments starting with one % are no longer treated as comments; use two %% to write a comment.
Internal element IDs are now prefixed with the diagram's SVG element ID to prevent duplicates when rendering multiple diagrams; CSS or JS exact ID selectors should use attribute-ending selectors instead.
ELK layout edges now default to rounded right-angle segments instead of inheriting the global basis default; non-ELK layouts are unaffected.
Plain text labels now render as regular text rather than being treated as markdown by default; newline characters create line breaks, and markdown-like text is not misinterpreted.
Security 16
CSS sibling combinators are now handled in compileCSS.
Mermaid allows CSS injection applying to sibling elements of the diagram
Mermaid Architecture diagrams are vulnerable to prototype pollution
Mermaid configuration APIs allow prototype pollution
Mermaid radar diagrams are vulnerable to DoS
Mermaid XY Charts are vulnerable to an infinite loop DoS
Protections against prototype pollution have been increased.
XY charts now support zero-width x-axis ranges.
Unbalanced CSS styles in classDefs are prevented.
Creates CSS styles using the CSSOM.
Limits loops when all dates are excluded in Gantt diagrams.
Mermaid Gantt Charts are vulnerable to an Infinite Loop DoS
Mermaid: Improper sanitization of
classDefin state diagrams leads to HTML injectionMermaid: Improper sanitization of
classDefsin diagrams leads to CSS injectionMermaid: Improper sanitization of configuration leads to CSS injection
Blocks stylis scope escape.
New APIs and options 45
Keeps a recursive flow's entry node on top.
Adds the
elk.nodePlacementAlignmentconfiguration option.ER diagrams now support subgraphs.
Adds folder, bucket, console (terminal window), and browser shapes to flowcharts.
Adds a person shape, usable in flowcharts via
A@{ shape: person }.Flowchart subgraphs can be collapsed with
subgraphId@{ view: collapsed }.Adds legends for named line and bar series.
Architecture-beta diagrams add an align row or column directive for explicitly aligning services.
Adds a configuration option to make architecture diagrams render deterministically.
Adds the Cynefin framework as a beta diagram type for representing its five complexity domains.
ER attribute types can be optional, indicated with a ? suffix.
Pie charts support donut charts, legend positioning, and slice highlighting.
Adds Railroad Diagram support using ABNF input syntax.
Adds Railroad Diagram support using IR input syntax.
Adds Railroad Diagram support using EBNF input syntax.
Adds Railroad Diagram support using PEG input syntax.
Adds swimlane as a standalone diagram type with a dedicated layered orthogonal layout algorithm.
Extends treeView-beta with features useful for representing file and directory structures.
XY chart line plots support per-point text labels.
XY charts can rotate X-axis labels.
Block diagrams support all arrow types.
Sankey diagrams support custom node colors.
Flowcharts can use a datastore shape to represent data persistence.
Architecture-beta diagrams expose this fcose layout knob so authors can tune layout density and spread overlapping siblings.
A new Event Modeling diagram is available.
Architecture-beta diagrams expose this fcose layout knob so authors can tune layout density and spread overlapping siblings.
Sankey diagrams allow node padding to be configured.
Architecture-beta diagrams expose this fcose layout knob so authors can tune layout density and spread overlapping siblings.
Sankey diagrams allow node width to be configured.
Architecture-beta diagrams expose this fcose layout knob so authors can tune layout density and spread overlapping siblings.
Sankey diagrams support an outlined label style.
Adds the randomize config option for architecture diagrams, defaulting to false for deterministic layout.
Adds neo look styling across state, sequence, ER, requirement, mindmap, flowchart, class, timeline, and gitGraph diagrams; some include themes, drop shadows, or enhanced styling.
Adds an option to change timeline direction.
Adds a new TreeView diagram type.
Adds Wardley Maps as a beta diagram type, with component positioning, links, evolution stages, annotations, strategy markers, and theme integration.
Adds theme support for data label colour in xy charts.
Adds the showDataLabelOutsideBar option for xy charts.
Exports the AsyncIconLoader type for developers using icon loaders.
Adds solid and stick half-arrowheads, along with central connection support.
Exports the IconLoader type for developers using icon loaders.
Adds the Ishikawa diagram type.
Adds alias support for the new participant syntax.
Exports the SyncIconLoader type for developers using icon loaders.
Adds the venn-beta diagram type.
Performance 1
Uses fastdom to batch DOM measurements, with up to 25% speedup.
Behavior and default changes 11
C4 elements render through the unified shape system, using the new person shape.
Services are rendered in definition order, and more service IDs are supported.
Block padding and sanitized configuration are read dynamically instead of at module load time.
Gantt charts accept multiple excludes and includes lines, allowing long exclusion lists to be split into commented groups.
Generic classes support styling and callbacks.
TreeView diagrams accept box-drawing character input.
Sequence diagrams now render a background box behind alt/else section title labels.
The sequence diagram directive supports decimal start and increment values.
Class diagrams now allow notes in namespaces.
Routes label creation through createText, adding support for KaTeX and FontAwesome icons loaded via iconpacks in some older labels.
Supports edge animation when using the hand drawn look.
Fixes and other changes 73
Restores the edgePaths class on the rendered SVG edge group and updates flowchart, block, and user journey stylesheets to target it.
C4 element labels wrap according to c4.wrap again, keeping long descriptions within the configured c4.width.
Composition, aggregation, extension, dependency, and lollipop markers no longer scale with edge stroke width, keeping them outside the class box boundary.
With layout: elk, neo-look arrowheads and crow's-foot markers use the configured theme colours and stroke widths on the first render.
Fixes sibling blocks overlapping when one has a label wider than 200px.
Named attributes such as
$tags,$linkand$spriteare no longer clobbered to undefined when they arrive in an earlier positional slot of C4 statements.Allows classdefs to update text color in block diagrams.
Stops dagre layout from spamming warn-level logs on every node, edge, and cluster.
Fixes a
RangeError: Invalid array lengthcrash when rendering certain edges.Reverts the behavior change from #7672 because arrows between subgraphs are broken.
A diagram's own nodeSpacing and rankSpacing now take effect in the unified dagre layout.
Prevents icons from disappearing after strict security sanitization.
Radar charts show at most 32 ticks, even when ticks is set higher.
Fixes rendering of 3-circle Venn diagram unions.
Block label sanitization respects the current DOMPurify configuration.
ER attribute names and types can contain special characters, such as dots, when escaped with backticks.
Prevents a crash when a flowchart node shape is undefined.
Flowchart and state self-loop edges render as a single SVG path.
Dagre layout respects the direction keyword set per subgraph.
Gantt vertical markers render without affecting row layout or chart height.
Labeled higher-arity unions render even when their underlying pairwise unions are not declared.
Supports consecutive LaTeX expressions in node text.
Radar axis labels align according to angular position to prevent clipping.
Rect backgrounds use theme-aware fallback colors.
State diagram click tooltips render with mermaidTooltip.
Fixes invalid syntax between state and {.
Treemap labels render correctly in large nested diagrams.
Plot data is truncated to match the X-axis category count.
YAML frontmatter delimiters can be preceded by horizontal whitespace.
Arrow blocks now span the specified number of columns when using :n syntax.
Self-referential class multiplicity labels are no longer rendered multiple times.
Block diagram column widths no longer shrink when mixing different column spans.
Gantt diagrams now limit iteration for the excludes field.
Block diagram hexagon blocks now respect column spanning syntax.
The messageAlign label position is corrected for right-to-left arrows in sequence diagrams.
Unquoted axis, quadrant, and point labels accept CJK, emoji, Latin-1 accented characters, and other non-ASCII text.
Unquoted Wardley map component names can contain hyphens, including multi-word names; no-space arrows still tokenize correctly.
Unnecessary sanitization of Wardley map text is fixed.
Supports inline annotation syntax such as
class Shape <<interface>>.Allows :::className syntax inside composite state blocks.
Fixes parsing when
1is used as the right-side entity identifier after a cardinality alias.Prevents
<and&from being escaped when htmlLabels is false.Preserves the cause hierarchy when the effect is indented more than causes.
Expands the viewBox to prevent long pie chart titles from being clipped.
Prevents sequence diagrams from hanging when
asis used without a trailing space in participant declarations.Flowcharts now warn when a style statement targets a non-existent node.
Allows quoted string labels in architecture-beta diagrams.
Corrects the length of architecture diagram lines.
Prevents unintended opacity on SVG AWS icons containing rect elements.
Supports ComponentQueue_Ext to prevent parsing errors.
Ensures correct edge label rendering when flowchart htmlLabels is false.
Corrects edge label positioning.
Recognizes the '1' cardinality alias before relationship operators.
Prevents syntax errors when node names contain 'u', numbers, and decimals.
Restores readable outside-text color for done tasks in dark mode.
Corrects BT orientation arc sweep flags so merge and non-merge arrows bend in the correct direction.
Passes gitGraphConfig to renderer functions so directives are applied properly.
Restores the original hexagon implementation.
Respects markdownAutoWrap: false for flowchart markdown labels when htmlLabels is enabled, preventing text auto-wrapping.
Fixes mindmap rendering in ELK layout.
Fixes mindmap rendering when the number of Level 2 nodes exceeds 11.
Corrects block positioning when nested blocks span multiple columns.
Improves participant parsing and prevents recursive loops on invalid syntax.
Restores the original roundedRect implementation.
Prevents HTML tags from being escaped when rendering labels in the sandbox.
Allows colons in transition and state description text.
Fixes parsing so direction TD is recognized within subgraphs.
Corrects viewBox casing and makes SVGs responsive.
In dark theme, derives taskTextDarkColor from doneTaskBkgColor for readable done-task text.
Positions tooltips near the hovered element.
Fixes treemap classDef style application so user-defined styles are applied.
Prevents browser hangs when accDescr is multiline in XY charts.
Validates dates and tick interval to prevent UI freezes or crashes in Gantt diagrams.
mermaid 103 changes
Security 2
Backports a dependency update to address CVE-2025-57347.
The v10.x branch supports newer DOMPurify versions, avoiding CVE-2025-26791.
Deprecations 1
The mermaidAPI.setConfig() function is deprecated.