feat(erDiagram): add subgraph support

[RodrigojndSantos]

📑 Summary

This PR introduces support for subgraphs in Entity Relationship (ER) diagrams, enabling entities to be grouped into logical domains. This improves diagram clarity and allows better structuring of complex diagrams, including support for nested subgraphs and relationships across different subgraph scopes.

Resolves #7417

📏 Design Decisions

The parser was extended to support ER subgraph syntax, including nested subgraphs. Subgraphs can be defined using different formats :

• A single identifier, which is used as both the id and the title.

subgraph id-title
    graph definition
end

• A quoted value for multi-word identifiers, where the same value is used as both id and title.

subgraph "id and title"
    graph definition
end

• An explicit id [title] notation, allowing the identifier and display title to be defined separately.

subgraph id [title]
    graph definition
end

The database was updated to store subgraphs as core structures in the model, similar to entities, adding support for subgraph storage, lookup, and id management. Relationship logic was adapted to allow subgraphs as valid endpoints, enabling relationships between entities and subgraphs. The data preparation step was updated to treat subgraphs as grouped nodes while preserving existing entity behavior. Existing class, style, and configuration handling were reused to ensure consistent rendering.

The example below illustrates the main behavior of the feature:

erDiagram
   subgraph sub1 [Customer Domain]
       customer
       subgraph sub1_1 [Account Details]
          direction LR
          checking_account
          savings_account
       end
   end

   subgraph "Bank Branch"
       branch
   end

   sub1 }|--|| "Bank Branch" : "assigned to"
   customer ||--|{ sub1_1 : "owns"
   checking_account ||--|{ savings_account : "linked to"
   sub1 }|--|| branch : "managed by"

   customer {
       id
       name
   }
   checking_account {
       account_number
       balance
   }
   savings_account {
       account_number
       balance
   }
   branch {
       branch_id
       location
   }

   style sub1 fill:#e6f2ff,stroke:#2c3e50,stroke-width:2px

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added necessary unit/e2e tests.
• 📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
• 🦋 If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

[changeset-bot]

🦋 Changeset detected

Latest commit: c81fcd4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
mermaid	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	c81fcd4
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/6a29a8328fb22900080cb6a9
😎 Deploy Preview	https://deploy-preview-7792--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[pkg-pr-new]

Open in StackBlitz

@mermaid-js/examples

npm i https://pkg.pr.new/@mermaid-js/examples@7792

mermaid

npm i https://pkg.pr.new/mermaid@7792

@mermaid-js/layout-elk

npm i https://pkg.pr.new/@mermaid-js/layout-elk@7792

@mermaid-js/layout-tidy-tree

npm i https://pkg.pr.new/@mermaid-js/layout-tidy-tree@7792

@mermaid-js/mermaid-zenuml

npm i https://pkg.pr.new/@mermaid-js/mermaid-zenuml@7792

@mermaid-js/parser

npm i https://pkg.pr.new/@mermaid-js/parser@7792

@mermaid-js/tiny

npm i https://pkg.pr.new/@mermaid-js/tiny@7792

commit: c81fcd4

[codecov]

Codecov Report

❌ Patch coverage is 0% with 185 lines in your changes missing coverage. Please review.
✅ Project coverage is 2.80%. Comparing base (2f4e702) to head (c81fcd4).
⚠️ Report is 455 commits behind head on develop.

Files with missing lines	Patch %	Lines
packages/mermaid/src/diagrams/er/erDb.ts	0.00%	181 Missing ⚠️
packages/mermaid/src/diagrams/er/styles.ts	0.00%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7792      +/-   ##
==========================================
- Coverage     3.27%   2.80%   -0.47%     
==========================================
  Files          598     669      +71     
  Lines        60420   73038   +12618     
  Branches       913     992      +79     
==========================================
+ Hits          1980    2051      +71     
- Misses       58440   70987   +12547     

Flag	Coverage Δ
unit	2.80% <0.00%> (-0.47%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/mermaid/src/diagrams/er/erTypes.ts	100.00% <ø> (ø)
packages/mermaid/src/diagrams/er/styles.ts	0.00% <0.00%> (ø)
packages/mermaid/src/diagrams/er/erDb.ts	0.00% <0.00%> (ø)

... and 170 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	👍 Changes approved	15 added	Jun 10, 2026, 6:14 PM

[pbrolin47]

Hi @RodrigojndSantos .
Thanks for this PR that will improve the er diagrams. Some initial comments to address:

[sisyphos-bot]

---

What's working well

🎉 Sound architectural pattern. The implementation mirrors flowchart's established subgraph model — isGroup: true nodes with parentId, delegating cluster rendering to the
shared rendering-util pipeline. This is the right approach; no new shared-code changes.

🎉 Strong parser/DB test coverage. subgraph.spec.js (332 lines) and erDb.spec.js thoroughly cover nested subgraphs, direction inheritance, makeUniq deduplication, and
cross-subgraph relationships. The edge cases around makeUniq are especially well thought out.

🎉 Correct title sanitization. Subgraph title goes through sanitizeText → common.sanitizeText → DOMPurify before storage. Confirmed by XSS sub-agent (no blocking security
findings).

🎉 Lexer cleanup is a good catch. Removing the dead SPACE token rule ([\s]+ was unreachable since \s+ came first) and switching to [ \t\r]+ is a correct fix that was
obscuring the grammar.

---

Security

XSS sub-agent reviewed all changed files and the full data flow. Summary of findings (all pre-existing patterns, not new regressions):

• 🟡 Subgraph id flows unsanitized to DOM id attributes via D3's .attr('id', node.domId). The JISON grammar restricts unquoted ids to \w|-|*|. characters, which excludes
  <, >, and ". Low risk in practice, consistent with flowchart's subgraph id behavior.
• 🟡 cssStyles on subgraphs follow the same unsanitized path as entity cssStyles (pre-existing for entities). DOMPurify's final pass on the complete SVG strips style
  attributes containing expressions.

No new XSS sinks or sanitization bypasses introduced.

---

Things to address

🔴 [blocking] — Missing E2E visual regression tests

styles.ts adds new .cluster rect, .cluster text, .cluster-label text rules. getData() now produces cluster nodes (isGroup: true). Nested subgraph layout, relationships
between subgraphs, and direction inheritance inside subgraphs are all new visual behaviors. Not one of these is covered by a Cypress screenshot test.

Per CLAUDE.md: "Any change that affects rendered SVG output [...] must add or update e2e tests." Unit tests verify that the DB stores the right data structures. They don't
verify that the layout engine correctly places cluster boundaries, that edge routing handles cross-subgraph relationships, or that the cluster styling renders correctly with
each theme.

At minimum, add a test in cypress/integration/rendering/erDiagram.spec.js using imgSnapshotTest covering:

• Simple subgraph with two entities
• Nested subgraphs
• Relationship between entities in different subgraphs (edge crossing cluster boundaries)
• Subgraph with direction override

---

🟡 [important] — setClass auto-creates entities: potential ghost nodes

Before this PR, setClass was a no-op if the entity didn't exist. The PR adds:

// erDb.ts:setClass (new code)
let entity = this.entities.get(id);
if (!entity) {
entity = this.addEntity(id); // ← NEW
}

If a user writes class UnknownId someStyle where UnknownId is neither a declared entity nor a subgraph, a ghost entity is now created and added to this.entities. Since
getData() iterates this.entities.keys() (filtering only known subgraph ids), this ghost entity will appear as a rendered node.

The existing behavior was intentional — setClass was a post-declaration step, not an entity creator. The comment says "Ensure entity exists so classes applied even if class
statement comes before entity," but this changes ER diagram behavior for all users. Verify this doesn't regress existing ER diagrams where class targets a typo or
non-existent name.

---

🟡 [important] — document rule push → concat change applies to all ER diagrams

-| document line {$1.push($2);$$ = $1}
+| document line { $$ = $1.concat($2); }

This change is necessary for subgraphs (statements now return arrays of entity names, so concat correctly flattens them). But it affects every ER diagram parse, not just
subgraph ones. The old push would add whatever line returned as a single element; concat flattens arrays one level.

Specifically: classDefStatement, classStatement, styleStatement, and some entityName SQS entityName SQE alternatives don't have explicit $$ = [...] assignments. JISON
defaults $$ to $1 in those cases, which would be the first token's value — a string, not an array. [].concat("string") = ["string"] (correct), but if any statement returns
an object that ends up in the document list, uniq's item.trim() call in addSubGraph would throw on non-string items.

This is likely fine in practice (the tests pass), but it's worth explicitly confirming with the existing ER diagram E2E suite rather than relying only on unit tests.

🟡 [important] — subgraph "Some Title" makes id === title, including the space

🟡 [important] — Please add a unit test for DB:getData() with cluster output

🟡 [important] — subgraph "Some Title" makes id === title, including the space

The docs correctly note: "If the subgraph identifier contains more than one word, it must be written in quotes. In this case, the quoted value is used both as the id and the title." So subgraph
"Customer Domain" gives id = Customer Domain (with space).

This means relationships involving space-containing subgraph ids must also use quoted syntax: "Customer Domain" }|--|| other. This is not documented. The test verifies the parse works but doesn't
demonstrate how to write relationships targeting quoted-id subgraphs. Consider adding a documentation example.

---

Nits

🟢 Dead code: _id === _title reference check (erDb.ts:addSubGraph)
if (_id === _title && /\s/.exec(_title.text)) {
id = undefined;
}
_id and _title are always different objects (created separately in the JISON action). This condition is always false. The id = undefined path (auto-generated subgraph ID) is unreachable. Copied
from flowchart's addSubGraph but doesn't apply here since ER's ENTITY_NAME token supports quoted strings with spaces as valid ids. Safe to remove.

🟢 makeUniq visibility — makeUniq is public but is only called internally. Should be private.

🟢 subgraphDepth visibility — subgraphDepth is public because JISON's yy object accesses it. A comment explaining this constraint would help future readers who'd otherwise wonder why a private
implementation detail is public.

🟢 private config = getConfig() capture — this.config is captured at ErDB construction time. If mermaid.initialize() is called after construction (as can happen in some integration patterns), the
securityLevel used for sanitizeText may differ from the live config. Pre-existing pattern from flowDb.ts:40 — not introduced by this PR, but worth noting.

---

[RodrigojndSantos]

Hi @pbrolin47 ,
Thank you for the detailed feedback and constructive review.
We’ve addressed the raised points as follows:

• Added end-to-end (Cypress) tests covering the scenarios you mentioned, including simple subgraphs (with id, id in quotes and id and title) nested subgraphs, relationships across subgraphs, and direction overrides. These tests explicitly validate the rendered SVG output via snapshot testing, as required.

• Added unit tests for getData(), ensuring the correct generation of cluster nodes and their structure.

• Improved the documentation regarding quoted identifiers (IDs with spaces), clarifying that they must be consistently referenced using quotes in relationships as well.

• Addressed the noted nits, as well.

Regarding the change from push to concat in the document rule, we validated the impact by running the full existing test suite (unit and E2E), which continues to pass without issues. This indicates that the previous behavior remains unchanged while correctly supporting the array-based returns introduced for subgraphs.
Regarding the security points, they appear to be pre-existing patterns and not directly related to the changes introduced in this PR, so we’ve kept the current behavior unchanged.

Ready for re-review.

[knsv-bot]

[sisyphus-bot]

Review: feat(erDiagram): add subgraph support

Thanks for this, @RodrigojndSantos — this is a genuinely well-executed feature. Subgraphs are one of the most-requested ER additions (#7417), and the way you've approached it — modelling subgraphs as isGroup cluster nodes with parentId, so they flow through the existing unified layout/cluster renderer rather than needing a custom ER renderer — is exactly the right call. The test suite is thorough and I was able to verify the important properties locally. A couple of small things to tidy, but nothing blocking. 🎉

What's working well

• 🎉 Architecture reuses the proven flowchart subgraph model. Mapping subgraphs to { isGroup: true, parentId, dir, look } nodes in getData() (erDb.ts) means clusters, nesting, and handdrawn all route through the shared rendering-util cluster code — no new renderer, minimal surface area, and you inherit the already-hardened rendering path.
• 🎉 Strong, multi-layered test coverage. parser/subgraph.spec.js (16 cases: nesting, per-subgraph direction, cross-subgraph relationships, quoted / id [title] / multi-word titles, empty subgraphs, whitespace-around-end), plus erDb.spec.js unit tests for getData() cluster output (isGroup/parentId parent-child wiring), makeUniq dedup, and subgraph-as-relationship-endpoint, plus 9 Cypress visual snapshots. This is the kind of coverage that makes a feature like this safe to land.
• 🎉 No regressions from the lexer rewrite. Reworking the whitespace handling (dropping the SPACE token in favour of significant NEWLINEs) is the riskiest part of the diff since it changes tokenization for every ER diagram. I ran the full existing ER suite against this branch and all 660 tests still pass, which is strong evidence the refactor is safe.
• 🎉 Nice bonus correctness fix: getData() now returns direction: this.direction instead of the previously hardcoded 'TB', so ER diagrams finally honour a top-level direction declaration.

Security

I ran a dedicated XSS/injection pass over the new code. No issues found. Subgraph titles are sanitized at DB-write time via common.sanitizeText (erDb.ts), the .cluster CSS in styles.ts:113-125 interpolates only theme variables (never diagram text), user style/cssStyles flow through the same grammar-constrained, DOMPurify-backstopped path flowchart uses, and the subgraph id is only ever set as a literal .attr('id', …) value — never into a selector or raw markup. The sanitization boundary matches the established flowchart baseline exactly.

Things to address

• 🟡 Handdrawn mode isn't demonstrated. The cluster nodes set look: config.look, so handdrawn should work for free via the shared cluster renderer — but there's no snapshot proving it. Per project convention, handdrawn support should either be demonstrated or explicitly noted as unavailable. Could you add one Cypress snapshot with { look: 'handDrawn' } (the existing er/erDiagram.spec.js cases make a good template)? That locks it in and confirms nothing breaks.

• 🟢 Edge case: accessibility/title statements inside a subgraph body leak as phantom nodes. I verified that erDiagram\nsubgraph G\nA\ntitle My Title\nend produces subgraph G.nodes === ["A", "title", "My", "Title"] — the title … line is split into bare entities instead of being treated as a title (or rejected). It's an unusual construct, so not blocking, but a small guard in addSubGraph's uniq() (or filtering non-node statements out of the document list) would make the membership logic more robust. Worth a quick test either way.

• 🟢 addSubGraph leans on any more than it needs to. const erConfig = (getConfig().er ?? {}) as any and the prims: any / objs: any[] scratch objects in uniq() — er.inheritDir is already a typed config option (it exists in config.schema.yaml / BaseDiagramConfig on develop), so getConfig().er?.inheritDir should type-check without the cast. The uniq() helper is a port of flowchart's, so I won't push hard, but tightening the types here would be a nice cleanup.

• 🟢 makeUniq silently drops a node that's already claimed by an earlier subgraph. This matches flowchart semantics (a node belongs to exactly one subgraph), and your erDb.spec.js test documents it well — but ER users coming from the entity-centric mental model may be surprised. A one-line log.warn when a node is dropped would make the behaviour discoverable. Non-blocking.

Process ✅

Changeset present (minor, feat:), docs updated in src/docs/ with the v<MERMAID_RELEASE_VERSION>+ placeholder (and the generated docs/ copy regenerated to match), and the PR links #7417. All good.

This is close — the handdrawn snapshot is the main thing I'd like to see, and the two 🟢 robustness items are quick. Really nice work on a long-requested feature. Let's get it landed. 🚀

[RodrigojndSantos]

Hi @knsv-bot,
thanks for the detailed review, we addressed all points:

• Hand-drawn mode: added snapshot coverage via the existing test matrix (options includes both handDrawn and elk). The new subgraph tests run under these modes, so hand-drawn rendering is now implicitly validated.

• Title / accessibility edge case: we investigated this and observed that title My Title already produces phantom entities even outside subgraphs. Given this existing behavior, we kept consistency for now and did not introduce special handling inside subgraphs. Let us know your thoughts. We did verify that accTitle, accDescr, and accDescription are correctly handled and do not leak into node membership.

• Type cleanup / direction handling: simplified subgraph direction logic to: dir = result.dir; If undefined, the renderer falls back to the default/global layout direction. Also reduced unnecessary complexity in uniq().

• Duplicate node handling: added the requested warning when a node is already assigned to another subgraph.

Please review and let us know your feedback. Thanks.

[pbrolin47]

Hi @RodrigojndSantos
Thanks for resolving the issues. I'll approve this PR.

[sisyphos-bot]

What's working well

🎉 All items from the two prior reviews have been addressed — this is a well-managed iteration, and the quality delta between the first and current version is significant.

🎉 The handdrawn mode concern is fully resolved. The tests are in erDiagram-unified.spec.js inside the testOptions.forEach() loop that includes { description: 'HD: ', options: {
logLevel: 1, look: 'handDrawn' } }, so all 2 new snapshot tests run under default, ELK, and handdrawn configurations — 6 visual assertions from 2 test bodies. This is exactly
the right approach.

🎉 The addSubGraph cleanup is clean. The erConfig as any complexity and the unreachable _id === _title dead-code check (copied from flowchart's version) are both absent. The
direction logic simplification to const dir = result.dir is much more readable.

🎉 makeUniq is correctly private, subgraphDepth has its visibility comment, and the log.warn for duplicate node membership is in place.

🎉 The getData() unit tests in erDb.spec.js are thorough — nested cluster parentId wiring, isGroup flags, and edges connected to subgraph endpoints are all covered.

🎉 The E2E coverage is solid: 8 cases in erDiagram.spec.js (simple, empty, nested, cross-subgraph relationships, quoted ids, explicit id+title, direction override) + 2 in the
unified spec under 3 rendering modes.

---

Security

XSS sub-agent review pending — incorporating findings below once complete.

Based on manual review of the diff:

• Subgraph title goes through this.sanitizeText(title) → common.sanitizeText(txt, this.config) → DOMPurify at DB-write time. ✓
• Subgraph id flows to node.id / node.domId in getData(), consistent with how flowchart subgraph ids are handled. The final DOMPurify.sanitize() in mermaidAPI.ts is the
  backstop. Same baseline as flowchart.
• .cluster CSS interpolations in styles.ts use only theme variables (options.clusterBkg, options.mainBkg, options.clusterBorder, options.titleColor, options.textColor) — these
  are never user-supplied diagram text.
• No new innerHTML, eval, D3 .html(), or other unsafe DOM sinks introduced.

---

Remaining open items

None blocking. The title My Title inside subgraph producing phantom entity nodes is an acknowledged pre-existing pattern (consistent behavior with entities outside subgraphs).
The setClass auto-entity-creation concern from the first review is pre-existing code — it's in the unchanged diff context, not introduced by this PR.

---