Mermaid XY charts for trends and data visualization

Most Mermaid diagrams show structure (flowcharts, ERDs) or interactions (sequence diagrams). But what if you want to plot data points and show relationships between two variables? That's where XY charts shine. Whether you're tracking performance metrics, analyzing correlations, or displaying scientific results, Mermaid's XY chart lets you embed data visualizations directly in your documentation—all in code, version-controlled, no images needed.

Why XY charts matter in technical documentation

Note: Mermaid's xychart-beta renders line and bar charts — not true scatter plots with individual point markers. You reveal relationships by plotting each variable as a line or bar series. For point-marker scatter plots, use a dedicated charting library.

XY charts are invaluable when:

• You need to show correlation — does memory usage correlate with response time? Plotting both as series makes it obvious.
• Trend analysis matters — plot historical data to show if a metric improves or degrades over time
• Outliers are important — a plotted series surfaces anomalies that summaries hide
• You want version control — unlike spreadsheets or screenshots, Mermaid code is git-friendly
• Data changes frequently — update the chart by editing the source, not exporting from a tool

XY charts are underused in technical docs, but they're perfect for incident reports, performance analysis, and capacity planning.

XY chart syntax in Mermaid

Mermaid's XY chart uses a simple, CSV-like syntax:

xychart-beta
    title "Performance: Memory vs Response Time"
    x-axis [100, 200, 300, 400, 500]
    y-axis "Response Time (ms)" 50 --> 500
    line [250, 300, 320, 350, 400]

Breaking it down:

• xychart-beta opens an XY chart
• title adds a headline
• x-axis defines the x-axis values (or range)
• y-axis defines the y-axis label and range
• line plots a data series as a connected line; bar plots the same data as bars

Here's a more realistic example with multiple series:

xychart-beta
    title API Latency by Request Size
    x-axis [1KB, 10KB, 100KB, 1MB, 10MB]
    y-axis "Latency (ms)" 0 --> 5000
    line [10, 15, 50, 200, 2500]
    line [12, 18, 55, 210, 2600]

You can plot multiple lines to compare datasets (e.g., before/after optimization, production vs. staging).

Real-world example: performance regression detection

Here's a line chart showing test execution time over 50 commits. You can spot the commit where performance degraded:

xychart-beta
    title "Test Suite Duration Over Time (commits)"
    x-axis [1, 10, 20, 30, 40, 50]
    y-axis "Duration (seconds)" 0 --> 120
    line [45, 47, 46, 48, 92, 95]

The jump from commit 30 to 40 is obvious—a regression was introduced. You'd then inspect commits 31–39 to find the culprit. This is far more actionable than a summary like "tests take ~50 seconds."

Multiple series on one chart

While Mermaid's XY chart is limited to X and Y, you can plot multiple series to show trends:

xychart-beta
    title "Database Query Performance: Index Impact"
    x-axis [100, 1000, 10000, 100000, 1000000]
    y-axis "Query Time (ms)" 0 --> 500
    line [2, 5, 15, 150, 1500]
    line [2, 5, 15, 30, 45]

The first line (without index) shows exponential degradation. The second line (with index) stays flat. The gap between them shows the index's benefit.

Use case: correlation analysis

Imagine you're investigating whether code churn correlates with bug reports:

xychart-beta
    title "Code Churn vs Bug Reports (per sprint)"
    x-axis [Sprint 1, Sprint 2, Sprint 3, Sprint 4, Sprint 5]
    y-axis "Bug Reports" 0 --> 30
    line [8, 15, 22, 18, 12]

Plot lines for both metrics:

• Line 1: files changed per sprint (scaled to 0–30)
• Line 2: bugs reported per sprint

If the lines trend together, there's a correlation. If they diverge, other factors are at play.

Best practices for XY charts

1. Scale axes for clarity — if one metric ranges 0–10 and another 0–1000, scale them proportionally so comparison is fair
2. Label both axes — always include units (ms, GB, %, count) so readers understand the data
3. Use clear titles — "API Latency by Payload Size" is better than "Performance"
4. Avoid clutter — limit to 2–4 series; more than that becomes hard to read
5. Include context — add a note about when data was collected or what conditions apply
6. Highlight significance — if a threshold matters (e.g., SLA is 200ms), mention it in the body

When to use XY charts vs. other Mermaid diagrams

Use XY Charts For	Use Gantt For	Use Pie Chart For
Correlation & trends	Timelines & scheduling	Percentages & proportion
Trend analysis	Project planning	Category breakdown
Performance metrics	Dependency tracking	Market share, budget
Time-series data	Release roadmaps	Composition

If you're plotting data over time and the duration of tasks matters, a Gantt chart is better. If you're showing percentages, a pie chart is clearer.

Exporting and embedding XY charts

In MermaidCreator, render your XY chart, then:

1. Export as PNG or SVG for presentations or reports
2. Copy the Mermaid code and paste into your README, wiki, or documentation
3. Embed in Markdown (GitHub, GitLab, Notion) — the diagram renders automatically

```mermaid
xychart-beta
    title Your Chart
    x-axis [1, 2, 3]
    y-axis "Label" 0 --> 10
    line [5, 8, 3]

## Limitations and workarounds

| Limitation | Workaround |
| --- | --- |
| Only X and Y (no Z-axis) | Use multiple series to compare datasets or use a heatmap-style approach |
| No point markers (line and bar only) | Use a table or a dedicated charting library if individual points matter |
| Data points are limited to the axis values | Consider a summary table for detailed data; use the chart for trends |
| No statistical overlays (e.g., trend line) | Describe the pattern in accompanying text ("trending upward by ~5% per sprint") |

## FAQ

**Can I plot real-time data in an XY chart?**  
No—Mermaid charts are static. For live dashboards, use a tool like Grafana or Datadog. Use Mermaid XY charts for historical analysis and documentation.

**How many data points can I include?**  
Mermaid doesn't have a hard limit, but readability degrades past ~50 points. For large datasets, aggregate by time period (e.g., daily instead of hourly) or visualize a sampling.

**Can I use XY charts for 3D data?**  
Not natively. Use multiple 2D charts side-by-side or include a data table for the third dimension.

**Can Mermaid's XY chart draw a scatter plot?**  
Not exactly. `xychart-beta` renders line and bar charts, not individual point markers. You can still reveal correlations by plotting each variable as a line series; for a true scatter plot with point markers, reach for a dedicated charting library.

**Should I use XY charts in architecture docs?**  
Yes, if you're documenting performance characteristics, capacity, or trade-offs. For example: "Database query time vs. dataset size" or "Memory usage vs. feature count."

Visualize your data trends in the [MermaidCreator editor](/playground). XY charts bring data to life in your documentation—no screenshots, no external tools, just code and version control.