Mermaid XY Chart Tutorial: Plot Bar and Line Charts in Code

# Mermaid XY Chart Tutorial: Plot Bar and Line Charts in Code

Mermaid.js added a powerful new diagram type called xychart-beta that lets you plot bar charts and line charts directly in Markdown using plain text. No spreadsheet, no image exports — just code.

This tutorial covers the full syntax, real-world examples, and tips to get clean, readable charts inside any tool that renders Mermaid diagrams.

What Is the Mermaid XY Chart?

The xychart-beta type (introduced in Mermaid v10.3) renders Cartesian charts with a horizontal X axis and a vertical Y axis. It supports two series types:

• bar — vertical bars for comparing categories
• line — connected points for showing trends over time

You can combine both on the same chart, which makes it useful for things like comparing actual vs. target metrics.

Basic Syntax

Every XY chart follows this structure:

xychart-beta
    title "Monthly Revenue"
    x-axis [Jan, Feb, Mar, Apr, May, Jun]
    y-axis "Revenue (USD)" 0 --> 50000
    bar [12000, 18000, 23000, 19000, 31000, 42000]

Key elements:

• title — optional chart heading
• x-axis — list of category labels in square brackets
• y-axis — optional label and min/max range (0 --> 50000)
• bar or line — data series as a comma-separated list

Bar Chart Example: Sales by Product

xychart-beta
    title "Q2 Sales by Product"
    x-axis ["Widget A", "Widget B", "Widget C", "Widget D"]
    y-axis "Units Sold" 0 --> 500
    bar [320, 180, 450, 270]

Use this pattern for any comparison across discrete categories — product sales, support tickets by team, test scores by class.

Line Chart Example: Weekly Active Users

xychart-beta
    title "Weekly Active Users"
    x-axis ["Week 1", "Week 2", "Week 3", "Week 4", "Week 5", "Week 6"]
    y-axis "Users" 0 --> 10000
    line [2400, 3100, 4500, 4200, 6800, 8900]

Line charts are better than bar charts when you want to show momentum or growth over time.

Combining Bar and Line on One Chart

You can overlay series by adding both bar and line blocks:

xychart-beta
    title "Revenue vs. Target"
    x-axis [Jan, Feb, Mar, Apr, May]
    y-axis "USD" 0 --> 60000
    bar [28000, 32000, 41000, 38000, 52000]
    line [30000, 30000, 35000, 40000, 45000]

The bar series shows actuals; the line shows the monthly target. This dual-series approach is popular in engineering dashboards and sprint retrospectives.

Real-World Use Cases

Sprint velocity — plot story points completed per sprint (bar) with a rolling average (line) to spot team trends in your project README.

API response time — chart p50/p95 latency over deploys without leaving your architecture documentation.

CI pipeline duration — track build times week over week directly in your repo's CHANGELOG.

Feature adoption — embed in a product spec document to show activation rate ramp after a launch.

Tips and Gotchas

Use quotes around multi-word labels. If an x-axis label has spaces, wrap it in double quotes: ["Week 1", "Week 2"]. Without quotes, Mermaid may parse the space as a delimiter and produce unexpected output.

Set explicit y-axis ranges. If you skip the 0 --> N range, Mermaid auto-scales, which can make small differences look dramatic. For honest data visualization, always set a baseline of 0.

xychart-beta is still a beta feature. The -beta suffix means the syntax may shift in future Mermaid releases. If you pin a Mermaid version in your project (e.g., in a package.json), the chart will stay stable.

Theme support is limited. XY charts respect the global Mermaid theme (default, dark, forest, etc.) for background and axis colors, but per-series color overrides via %%{init}%% directives are not fully supported yet.

Customizing with Init Directives

You can nudge chart dimensions and colors using the init block at the top:

%%{init: {'theme': 'dark', 'xyChart': {'width': 800, 'height': 400}}}%%
xychart-beta
    title "Dark Mode Chart"
    x-axis [Q1, Q2, Q3, Q4]
    y-axis "Revenue" 0 --> 100000
    bar [45000, 62000, 71000, 89000]

Setting width and height is especially helpful when embedding charts in documentation sites where the default canvas feels too small.

Where to Use XY Charts

Mermaid XY charts render anywhere Mermaid is supported:

• GitHub — in README files, issues, pull request descriptions, and wikis (fenced `mermaid blocks)
• GitLab — same fenced code block support
• Notion — via the /code block with Mermaid selected
• Obsidian — with the Mermaid plugin enabled
• Docusaurus / MkDocs — via official Mermaid integrations

For instant preview and PNG/SVG export without any setup, open MermaidEditor.lol — paste the code and your chart renders immediately.

Quick Reference

Try It Now

Copy any example above and paste it into the Mermaid Live Editor →. Tweak the numbers, switch bar to line, change the theme — the preview updates instantly.

For more diagram types:

- Mermaid Pie Chart Tutorial

- Mermaid Gantt Chart Examples

- Mermaid Diagram Types Overview