Add legends to XY charts

[xdumaine]

📑 Summary

Adds legends for named XY chart line and bar series. Authors can already write labels like line "avg" [...]; this change preserves those labels and renders them in a right-side legend when showLegend is enabled.

Fixes #5292.

Motivation

XY charts support multiple line and bar plots, but readers currently have no built-in way to map each plotted color to a series name. That makes examples like average, p50, and p95 latency lines hard to interpret without surrounding text or manually faked legends.

This PR makes the existing named-series syntax useful in rendered output while keeping unnamed plots unchanged.

📏 Design Decisions

• Reuses existing plot labels from line "name" [...] and bar "name" [...]; no new diagram syntax is required.
• Omits unnamed plots from the legend so existing charts do not gain placeholder entries.
• Adds a ChartLegend layout component that reserves right-side space before the plot expands into remaining width.
• Adds xyChart.showLegend, legendFontSize, legendPadding, and themeVariables.xyChart.legendTextColor for configuration/theming.
• Documents the feature with the required (v<MERMAID_RELEASE_VERSION>+) marker and includes a minor changeset.

Screenshots

Full chart with legend:

Legend detail:

Disclaimer / Methods

I used Cursor's AI coding agent with GPT 5.5. to help inspect Mermaid's XY chart and pie legend implementations, draft the implementation, update docs/config/types, and run verification. I reviewed the generated changes, corrected the implementation where needed, checked the contribution guidelines and PR template, and validated behavior locally with parser, TypeScript, lint, and focused Cypress rendering tests.

Test plan

• pnpm --filter mermaid types:build-config

• pnpm exec prettier --write "packages/mermaid/src/diagrams/xychart/**/*.{ts,js}" "packages/mermaid/src/themes/*.js" "packages/mermaid/src/docs/syntax/xyChart.md" "docs/syntax/xyChart.md" "cypress/integration/rendering/xychart/xyChart.spec.js" "packages/mermaid/src/schemas/config.schema.yaml" "packages/mermaid/src/config.type.ts"

• pnpm exec vitest run packages/mermaid/src/diagrams/xychart/parser/xychart.jison.spec.ts

• pnpm exec vitest run packages/mermaid/src/diagrams/xychart/chartBuilder/components/legend.spec.ts packages/mermaid/src/diagrams/xychart/xychartDb.spec.ts packages/mermaid/src/diagrams/xychart/parser/xychart.jison.spec.ts packages/mermaid/src/themes/theme-xychart.spec.js (67/67 passing)

• pnpm exec vitest run --coverage packages/mermaid/src/diagrams/xychart/chartBuilder/components/legend.spec.ts packages/mermaid/src/diagrams/xychart/xychartDb.spec.ts packages/mermaid/src/themes/theme-xychart.spec.js

• pnpm test:check:tsc

• pnpm exec eslint --quiet packages/mermaid/src/diagrams/xychart/chartBuilder/components/legend.ts packages/mermaid/src/diagrams/xychart/chartBuilder/components/legend.spec.ts packages/mermaid/src/diagrams/xychart/chartBuilder/interfaces.ts packages/mermaid/src/diagrams/xychart/xychartDb.spec.ts packages/mermaid/src/themes/theme-xychart.spec.js cypress/integration/rendering/xychart/xyChart.spec.js

• MERMAID_PORT=9000 pnpm run load:env -- start-server-and-test dev http://localhost:9000/ "cypress run --spec cypress/integration/rendering/xychart/xyChart.spec.js" (38/38 passing)

📋 Tasks

• 📖 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:.

Made with Cursor

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	0872879
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/6a29947ec4c6880008d332e9
😎 Deploy Preview	https://deploy-preview-7724--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.

[changeset-bot]

🦋 Changeset detected

Latest commit: 0872879

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

[pkg-pr-new]

Open in StackBlitz

@mermaid-js/examples

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

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: 0872879

[codecov]

Codecov Report

❌ Patch coverage is 1.29032% with 153 lines in your changes missing coverage. Please review.
✅ Project coverage is 2.81%. Comparing base (9030126) to head (0872879).
⚠️ Report is 55 commits behind head on develop.

Files with missing lines	Patch %	Lines
...diagrams/xychart/chartBuilder/components/legend.ts	0.83%	119 Missing ⚠️
.../src/diagrams/xychart/chartBuilder/orchestrator.ts	0.00%	22 Missing ⚠️
packages/mermaid/src/diagrams/xychart/xychartDb.ts	0.00%	2 Missing ⚠️
packages/mermaid/src/themes/theme-base.js	0.00%	1 Missing ⚠️
packages/mermaid/src/themes/theme-dark.js	0.00%	1 Missing ⚠️
packages/mermaid/src/themes/theme-forest.js	0.00%	1 Missing ⚠️
packages/mermaid/src/themes/theme-neo-dark.js	0.00%	1 Missing ⚠️
packages/mermaid/src/themes/theme-neo.js	0.00%	1 Missing ⚠️
packages/mermaid/src/themes/theme-neutral.js	0.00%	1 Missing ⚠️
packages/mermaid/src/themes/theme-redux-color.js	0.00%	1 Missing ⚠️
... and 3 more

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7724      +/-   ##
==========================================
- Coverage     2.83%   2.81%   -0.02%     
==========================================
  Files          667     670       +3     
  Lines        72262   72876     +614     
  Branches       989     992       +3     
==========================================
+ Hits          2047    2051       +4     
- Misses       70215   70825     +610     

Flag	Coverage Δ
unit	2.81% <1.29%> (-0.02%)	⬇️

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

Files with missing lines	Coverage Δ
packages/mermaid/src/config.type.ts	100.00% <ø> (ø)
...id/src/diagrams/xychart/chartBuilder/interfaces.ts	10.00% <ø> (ø)
packages/mermaid/src/themes/theme-default.js	95.88% <100.00%> (+<0.01%)	⬆️
packages/mermaid/src/themes/theme-base.js	2.09% <0.00%> (-0.01%)	⬇️
packages/mermaid/src/themes/theme-dark.js	1.90% <0.00%> (-0.01%)	⬇️
packages/mermaid/src/themes/theme-forest.js	2.10% <0.00%> (-0.01%)	⬇️
packages/mermaid/src/themes/theme-neo-dark.js	2.40% <0.00%> (-0.01%)	⬇️
packages/mermaid/src/themes/theme-neo.js	2.49% <0.00%> (-0.01%)	⬇️
packages/mermaid/src/themes/theme-neutral.js	2.64% <0.00%> (-0.01%)	⬇️
packages/mermaid/src/themes/theme-redux-color.js	2.28% <0.00%> (-0.01%)	⬇️
... and 6 more

... and 46 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 detected (Review)	1 added	Jun 10, 2026, 5:07 PM

[pbrolin47]

Hi @xdumaine. Thanks for this PR.

[sisyphus-bot]

---

What's working well

🎉 Comprehensive test coverage for a first-time contributor. Four new test files covering legend unit tests, chart builder integration, DB title persistence, and all 11 themes. 79/79 unit tests +
38/38 Cypress passing is the complete picture the project expects.

🎉 Clean architectural fit. ChartLegend implements the existing ChartComponent interface without any deviation. Reserving space before expanding the plot to fill remaining width is exactly the right
layout approach — same pattern as the title component.

🎉 Elegant backwards-compatible syntax. Reusing line "name" [...] (already parseable; title was previously ignored) means zero new grammar and existing unnamed charts are completely unaffected.

🎉 Correct sanitization. title: textSanitizer(title.text) in both setLineData and setBarData matches the established pattern for every other user-supplied text field in this diagram. No XSS path —
text reaches SVG exclusively via D3's .text() (sets textContent, not innerHTML).

🎉 Config schema first. Schema additions drive config.type.ts regeneration; PR body includes pnpm types:build-config in the test plan. The regenerated file matches the schema additions exactly.

---

Things to address

🟡 [important] showLegend: true by default changes rendering for existing documents

config.schema.yaml:
showLegend:
description: Should show a legend for named plots
type: boolean
default: true

Any existing diagram that already uses line "name" [...] or bar "name" [...] syntax — including documents on GitHub, GitLab, Obsidian — will now automatically render a legend box, changing their
layout dimensions and visual appearance.

CLAUDE.md is explicit: "Mermaid is rendered server-side by GitHub/GitLab — rendering changes affect millions of existing documents. Treat visual output changes as potentially breaking."

The counter-argument (acknowledged in the PR description) is that users who wrote line "avg" [...] expected the name to mean something — they were already opting in to the feature by using the
named-series syntax. That logic is sound, and it means unnamed charts are truly unaffected.

I would like some additional input from other maintainers if we should go for showLegend: true as default or flip to false. @aloisklink , @knsv ?

The existing Cypress imgSnapshotTest cases don't use named series, so no baseline failures are expected regardless.

🟢 [nit] Cypress legend test uses screenshot: false only

cypress/integration/rendering/xychart/xyChart.spec.js:
it('should render legends for named plots', () => {
renderGraph(..., { screenshot: false });
cy.get('g.legend text').should('have.length', 3);
// ...

The test correctly verifies DOM structure (element counts and text content). But without an imgSnapshotTest call, visual regressions — wrong marker size, misaligned text, wrong color — won't be
caught in Argos / the snapshot pipeline. An additional imgSnapshotTest case with the same three-series diagram would add meaningful regression coverage. Low priority since the unit tests cover
positioning math, but worth noting.

---

Security

No XSS or injection issues. Full trace:

1. line "name" → JISON calls setLineData({ text: 'name', type: 'text' }, [...]) with '' for unnamed plots
2. textSanitizer(title.text) → sanitizeText(text.trim(), config) → DOMPurify-backed sanitization, matching all other text in this diagram
3. plot.title flows to DrawableElem type: 'text'
4. xyChartRenderer.ts:242 — d3.text((data) => data.text) sets .textContent, never .innerHTML
5. Legend marker geometry (path strings, x/y/width/height) is derived entirely from layout arithmetic on numeric config values — no user input

getPlotColorFromPalette() supplies fill/strokeFill values set as D3 .attr('fill', ...) / .attr('stroke', ...) — the existing risk surface, no new exposure.

---

Other checks

• Diagram isolation ✓ — legend.ts imports only from interfaces.js, textDimensionCalculator.js, and diagram-api/types.js. No cross-diagram imports.
• Changeset ✓ — minor bump with feat: prefix. Correct for a new user-facing feature.
• No console.log ✓
• TypeScript ✓ — title: string added as required field on LinePlotData/BarPlotData, and the only creation site (xychartDb.ts) populates it in both setLineData and setBarData. No existing code
  creates these types directly.
• MERMAID_RELEASE_VERSION ✓ — Added in commit 2/3 to the new Legend section heading.
• Unnamed-plot filter ✓ — filter((plot) => plot.title) correctly excludes title: '' (falsy), matching the described behavior.
• Legend visibility fallback ✓ — When legend dimensions exceed available space, visiblePlots is reset to [] and calculateSpace returns {0, 0}. Silent but correct behavior; space is returned to the
  plot.
• Both orientations covered ✓ — Vertical and horizontal layout paths both call legend.calculateSpace() and legend.setBoundingBoxXY().

---

[xdumaine]

Great call out re: defaulting the legend to true. However, based on the end of that block (quoted below) I'm going to wait for feedback before flipping that. I'm happy to go either way and glad to make that change once there's consensus. Thank you for the review!

I would like some additional input from other maintainers if we should go for showLegend: true as default or flip to false. @aloisklink , @knsv ?

[xdumaine]

@aloisklink @knsv any preference? I'm glad to update it per your guidance. Would love to get this landed.

[aloisklink]

Great work on this, @xdumaine! I'm really like this!

I think keeping showLegend: true by default is fine. Most people would probably be happy to see this, and it's not going to significantly negatively affect this XY charts for other users.

But on the off chance someone doesn't like it, could you maybe add a short instruction on how to disable this in the changeset?

I've done a quick review of your code as well, and I think the main blocking issue I spotted was the lack of visual regression E2E tests (the current @argos-ci changes are all flakiness that should be gone the next time you push), but please see my comments for more information!

---

I'm going to ping @subhash-halder, the original author of XY charts, in case they want to review this (and also so they can see how awesome this feature is!).

[xdumaine]

@aloisklink polite bump please and thank you

[aloisklink]

Looks good to me! Thanks for the reminder.

I've got one nitpick (useless type cast, very common with LLM-generated code), but I'll apply that myself so we can merge the PR now!

As a heads up, we've already cut off the release/11.16.0 branch, so this probably won't land in the next release, but only the release after that.

[mermaid-bot]

@xdumaine, Thank you for the contribution!
You are now eligible for a year of Premium account on MermaidChart.
Sign up with your GitHub account to activate.