MermanDraw
Open Editor

Mermaid guide

Mermaid XY Chart: Bar and Line Charts from Plain Text

The XY chart draws bars and lines on a shared axis pair. You give it categories or a numeric range for x, a range for y, and one or more series as arrays of numbers. It is enough for a metrics snapshot in a README or a status page without pulling in a charting library.

Multiple series stack visually (a bar and a line with the same data is a common way to show a trend over totals). All values are hard-coded in the text, so the chart is as fresh as the last edit.

  • metrics dashboards
  • time-series snapshots
  • before/after comparisons
  • lightweight reporting

Example

Mermaid XY Chart exampleMonthly Active UsersJanFebMarAprMayJun5000450040003500300025002000150010005000Users
xychart-beta
    title "Monthly Active Users"
    x-axis [Jan, Feb, Mar, Apr, May, Jun]
    y-axis "Users" 0 --> 5000
    bar [120, 380, 820, 1540, 2900, 4600]
    line [120, 380, 820, 1540, 2900, 4600]
Open in editor → Cheatsheet →

Syntax

Categorical x-axis

xychart-beta
    title "Signups per month"
    x-axis [Jan, Feb, Mar, Apr]
    y-axis "Signups" 0 --> 400
    bar [120, 180, 260, 350]
    line [120, 180, 260, 350]
Categorical x-axis — Mermaid xychartSignups per monthJanFebMarApr400350300250200150100500Signups

Quote the title and the y-axis label. The y range is optional; Mermaid fits to the data when omitted.

Try this snippet →

Numeric x-axis and orientation

xychart-beta horizontal
    title "Latency by percentile"
    x-axis "Percentile" 50 --> 99
    y-axis "ms" 0 --> 800
    line [120, 180, 260, 410, 790]
Numeric x-axis and orientation — Mermaid xychartLatency by percentile95908580757065605550Percentile0100200300400500600700800ms

horizontal after the keyword flips the axes. A numeric x-axis is written as min --> max.

Try this snippet →

Common mistakes

These are the parse errors that come up most, including in code written by ChatGPT and Claude. Paste any failing diagram into the editor and it marks the offending line.

  • Series length does not match the number of x categories.

    Fix: Give every series exactly one value per category. Missing values are not interpolated.

  • Unquoted title with spaces.

    Fix: title "Signups per month". Single words parse unquoted; anything with spaces needs quotes.

  • Writing xychart without -beta.

    Fix: In Mermaid 11 the keyword is still xychart-beta.

Real-world examples

Complete, copy-ready xy charts for common situations. Each one opens in the editor with a click.

Browse all examples →

FAQ

Can I add a legend?

Not yet. Describe the series in the title or caption, or use distinct colours via theme variables.

How many series can I plot?

There is no fixed limit, but readability drops after three or four. Split into several charts if you need more.