Mermaid XY Chart Tutorial: Bar and Line Charts from Text with xychart-beta
Mermaid's xychart-beta brings actual bar and line charts to the text-based world - define the axes, drop in your data arrays, and render a chart without a charting library.
Most Mermaid diagrams are about structure and flow, but sometimes a document needs a plain data chart - revenue by quarter, response time over a week, units sold by category. Reaching for a full charting library is overkill when the chart lives in Markdown alongside diagrams, and that is the gap "xychart-beta" fills. It renders genuine bar and line charts from a compact text definition: you set up the axes and provide the data as simple arrays, and Mermaid draws the plot.
This guide covers the xychart-beta syntax - orientation, axis definitions, and the bar and line series - with examples for the Mermaid editor at /diagram-tools/mermaid-editor. The rendered chart is editable in Atlas Diagram Studio at /diagrams, so you can restyle it to match a report. Because the input is close to raw data, an xychart is easy to update as numbers change, and the AI diagram generator at /diagram-tools/ai-diagram-generator can scaffold the axes and series from a description of the data you want to show.
Setting up axes
An xychart begins with "xychart-beta", optionally followed by "horizontal" to rotate the bars, and a "title" in quotes. The two axes are defined with "x-axis" and "y-axis". The x-axis is typically categorical for bar charts - you list the category labels in square brackets, as in "x-axis [Jan, Feb, Mar, Apr]" - while the y-axis is numeric and can be given a label and an explicit range, like 'y-axis "Revenue (thousands)" 0 --> 100'.
Defining the y-axis range explicitly is worth doing deliberately, because it controls how the data reads. A y-axis that starts at zero shows true proportions, while one that starts near the data's minimum exaggerates differences - a well-known way charts mislead. For honest reporting, start the y-axis at zero unless you have a specific reason not to, and if you do truncate it, be aware you are amplifying the visual differences between values.
Bar and line series
With the axes defined, you add the data as one or more series. The bullets below cover the series syntax and the options that shape the chart.
- Start with "xychart-beta" and optionally "horizontal" to make bars run sideways.
- Add a categorical x-axis: "x-axis [Q1, Q2, Q3, Q4]".
- Add a numeric y-axis with a label and range: 'y-axis "Revenue" 0 --> 100'.
- Draw bars with "bar [30, 45, 60, 80]", one value per x-axis category.
- Draw a line with "line [25, 40, 55, 70]", again one value per category.
- Include both a "bar" and a "line" series to overlay them on the same axes.
- Keep the number of values in each series equal to the number of x-axis categories, or the plot misaligns.
Reading and combining series
The most common structural mistake is a mismatch between the count of x-axis categories and the count of values in a series. Each value in a "bar" or "line" array corresponds positionally to a category on the x-axis, so four categories need four values; a shorter or longer array throws the alignment off and produces a confusing plot. Treat the category list as the spine and make every series line up with it exactly.
Overlaying a bar series and a line series on the same chart is a genuinely useful pattern - bars for the primary quantity and a line for a target or a trend, for instance. Mermaid draws them together against the shared axes, letting a reader compare actuals against a goal in one glance. Keep such combinations restrained, though; two series read cleanly, but piling on more competes for attention, and at some point a separate chart communicates better than a crowded one.
When xychart is the right tool
Xychart-beta is the right choice when you need a straightforward quantitative chart embedded in a text-based document - quarterly figures in a README, a metric trend in an RFC, category comparisons in a report. It is intentionally focused on bar and line charts, so it is not the tool for pie charts (use Mermaid's "pie"), for showing how quantities split and flow (use a "sankey-beta"), or for a positioning matrix (use a "quadrantChart"). Matching the chart type to the data's shape is what makes it read clearly.
Its closeness to raw data is the practical advantage: as the numbers update, you edit the arrays and the chart follows, with no separate export step. Build it in the Mermaid editor at /diagram-tools/mermaid-editor, style it for a report in Atlas Diagram Studio at /diagrams, and keep the source in version control next to the document. For the other data-oriented Mermaid diagrams and how to choose among them, the complete Mermaid guide at /guides/mermaid-js-complete-guide is the reference.