Mermaid XY Charts

Mermaid XY Charts (xychart-beta) are used to create clean, text-based line and bar charts. They are ideal for tracking metrics, financial performance, and technical data over time.

Example

xychart-beta
    title "Chart Title"
    x-axis [A, B, C, D]
    y-axis "Value" 0 --> 100
    bar [20, 40, 60, 80]

Structural Configuration & Core Settings

An XY chart initializes with the xychart-beta keyword. You must explicitly configure both the horizontal (X-axis) and vertical (Y-axis) parameters before inputting data series.

title: Sets the display name of your chart.
x-axis: Takes a structural array of categorical descriptive labels wrapped in square brackets (e.g., ["Jan", "Feb", "Mar"]).
y-axis: Takes a lower and upper numerical boundary range configuration (e.g., 0 --> 500 or 1000 --> 5000).

Example

xychart-beta
    title "Monthly Sales"
    x-axis [Jan, Feb, Mar, Apr, May]
    y-axis "Sales" 0 --> 100
    bar [30, 45, 60, 50, 75]

Rendering Data Series (Bar vs. Line)

You can choose to render your data series as solid blocks or as points connected by line intervals. You can also stack multiple charts in the same viewport.

bar: Creates a vertical bar graph column for each data point element array (e.g., bar [120, 240, 310]).
line: Creates a connected line path mapping across data point arrays (e.g., line [100, 210, 290]).
Array Length Match: The number of numerical items in your bar or line array must exactly match the number of category text items listed in your x-axis array.

Bar Chart

xychart-beta
    title "Monthly Sales"
    x-axis ["Jan", "Feb", "Mar"]
    y-axis "Sales" 0 --> 100
    bar [30, 50, 75]

Line Chart

xychart-beta
    title "Monthly Users"
    x-axis ["Jan", "Feb", "Mar"]
    y-axis "Users" 0 --> 100
    line [30, 45, 70]

Important Layout Constraints

Beta Syntax Limitations: Because the XY chart feature is currently in a beta implementation cycle, advanced individual data styling (like assigning specific custom hex codes to individual data bars or lines) is not yet supported natively. Themes must be handled via global Mermaid config headers.
Auto-Color Rotation: When you layer multiple data trends (e.g., adding two separate line elements or a bar and a line), Mermaid automatically alternates color presets to keep them visually distinct.

More Examples

Bar + Line

xychart-beta
    title "Sales Performance"
    x-axis [Q1, Q2, Q3, Q4]
    y-axis "Revenue" 0 --> 100
    bar [40, 60, 55, 80]
    line [35, 55, 65, 75]

Numeric X-Axis

xychart-beta
    title "Temperature"
    x-axis "Day" 1 --> 7
    y-axis "Temperature (°C)" 0 --> 40
    line [25, 27, 29, 31, 30, 28, 26]