Deprecate flowchart-level htmlLabels config option

[darshanr0107]

📑 Summary

This PR deprecates the flowchart.htmlLabels configuration option in favor of using the root-level htmlLabels setting. This change fixes inconsistent behavior where both configuration options existed but had unclear precedence, which could lead to unexpected results in your diagrams.

This PR also fixes class diagram, ER diagram, and requirement diagram edge labels rendering using HTML, even when the root level htmlLabels was set to false. They now no longer use <foreignObject> when htmlLabels: false is set (see @argos-ci changes).

FIxes #1431

What Changed and Why

The Problem

Previously, Mermaid supported two ways to configure HTML labels:

1. Root-level: htmlLabels: true
2. Flowchart-specific: flowchart.htmlLabels: true
   When both were set, the behavior was inconsistent and confusing.

The Solution

Now, root-level htmlLabels is the single source of truth. The root-level setting:

• Applies consistently across all diagram types
• Takes precedence over any diagram-specific settings
• Provides a clearer, more predictable configuration experience

The old flowchart.htmlLabels option still works for backward compatibility,
but:

• Shows a deprecation warning in the console
• Will be removed in a future version
• Is ignored when root-level htmlLabels is also set

📖 What You Need to Know

For Most Users: No Action Required

If you're not using flowchart.htmlLabels in your configuration, you don't need to do anything. Your diagrams will continue to work exactly as before.

If You're Using flowchart.htmlLabels: Simple Migration

If you currently have code like this:

//  Old way (deprecated)
mermaid.initialize({
  flowchart: {
    htmlLabels: true
  }
});

Simply move it to the root level:

// New way (recommended)
mermaid.initialize({
  htmlLabels: true
});

🔍 Examples

Before:

---
config:
  flowchart:
    htmlLabels: false
---
graph TD
    A --> B

After:

---
config:
  htmlLabels: false
---
graph TD
    A --> B

Note:Fixed class diagram, ER diagram, and requirement diagram edge labels rendering using HTML, even when the root level htmlLabels was set to false.

📏 Design Decisions

• AddedgetEffectiveHtmlLabels(config) to centralize logic.
• Root-level takes precedence;flowchart.htmlLabels logs a deprecation warning.
• Marked flowchart.htmlLabelsas deprecated in the schema.

📋 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: 2450a2f

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	2450a2f
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/695fb5273b56a40008527d6b
😎 Deploy Preview	https://deploy-preview-6995--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

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/mermaid/@mermaid-js/examples@6995

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: 2450a2f

[argos-ci]

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

Build	Status	Details	Updated (UTC)
default (Inspect)	👍 Changes approved	61 changed	Jan 8, 2026, 1:57 PM

[codecov]

Codecov Report

❌ Patch coverage is 16.66667% with 55 lines in your changes missing coverage. Please review.
✅ Project coverage is 3.58%. Comparing base (66f0c6c) to head (2450a2f).
⚠️ Report is 3 commits behind head on develop.

Files with missing lines	Patch %	Lines
packages/mermaid/src/dagre-wrapper/nodes.js	0.00%	10 Missing ⚠️
.../src/rendering-util/rendering-elements/clusters.js	0.00%	7 Missing ⚠️
packages/mermaid/src/dagre-wrapper/clusters.js	0.00%	5 Missing ⚠️
packages/mermaid/src/dagre-wrapper/edges.js	0.00%	4 Missing ⚠️
packages/mermaid/src/dagre-wrapper/shapes/util.js	0.00%	4 Missing ⚠️
packages/mermaid/src/dagre-wrapper/createLabel.js	0.00%	3 Missing ⚠️
...aid/src/rendering-util/rendering-elements/edges.js	0.00%	3 Missing ⚠️
...c/rendering-util/rendering-elements/shapes/util.ts	0.00%	3 Missing ⚠️
packages/mermaid/src/config.ts	80.00%	2 Missing ⚠️
packages/mermaid/src/dagre-wrapper/shapes/note.js	0.00%	2 Missing ⚠️
... and 6 more

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #6995      +/-   ##
==========================================
+ Coverage     3.57%   3.58%   +0.01%     
==========================================
  Files          474     473       -1     
  Lines        47498   47506       +8     
  Branches       734     739       +5     
==========================================
+ Hits          1696    1705       +9     
+ Misses       45802   45801       -1     

Flag	Coverage Δ
unit	3.58% <16.66%> (+0.01%)	⬆️

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

Files with missing lines	Coverage Δ
packages/mermaid/src/assignWithDepth.ts	90.69% <100.00%> (+0.22%)	⬆️
packages/mermaid/src/config.type.ts	100.00% <ø> (ø)
packages/mermaid/src/diagrams/common/common.ts	31.89% <100.00%> (+0.13%)	⬆️
packages/mermaid/src/config.ts	26.24% <80.00%> (+4.10%)	⬆️
packages/mermaid/src/dagre-wrapper/shapes/note.js	0.00% <0.00%> (ø)
...ges/mermaid/src/diagrams/class/classRenderer-v2.ts	0.36% <0.00%> (-0.01%)	⬇️
packages/mermaid/src/mermaidAPI.ts	0.30% <0.00%> (-0.01%)	⬇️
...c/rendering-util/rendering-elements/createLabel.js	0.00% <0.00%> (ø)
...c/rendering-util/rendering-elements/shapes/note.ts	0.00% <0.00%> (ø)
...ng-util/rendering-elements/shapes/rectWithTitle.ts	0.81% <0.00%> (ø)
... and 9 more

... and 1 file 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.

[aloisklink]

I've got some non-blocking comments, which I think will be good to fix before merging.

@darshanr0107, can we add the following to the PR description:

Fixes #1431

I think this PR closes it.

And since this PR is a deprecation notice and a bug fix PR, can you add some more details + examples to the PR description?

---

I wonder if it's also worth doing a squash merge, since this PR has 32 commits when it probably doesn't actually need that many 😬