Use Mermaid's xychart syntax to create a bar chart directly in Markdown. The examples below cover a basic bar chart, exact values, combined line and bar series, multiple series, and common rendering failures.
The mermaid fence tells a compatible Markdown viewer to draw the chart instead of displaying raw code. Mermaid's XY chart syntax is the most direct way to create a conventional bar chart. Mermaid currently documents the diagram as xychart, while some deployed renderers—including the version used by mdview.io at the time of writing—still recognize its earlier xychart-beta identifier. This example uses xychart-beta so it renders in mdview.io today.
The important lines are:
title supplies the chart heading.x-axis defines one category for each bar.y-axis adds a label and explicit numeric range.bar provides values in the same order as the categories.Keep the number of categories and values equal. If the x-axis lists three environments, the bar series should contain three numbers.
The opening fence is three backticks followed by mermaid. Put the chart identifier on the next line, then close the block with three backticks on a line by themselves. Here is the complete Markdown to copy, including its fences:
```mermaid
xychart-beta
x-axis [API, Web, Worker]
y-axis "Builds" 0 --> 50
bar [42, 28, 16]
```Do not write mermaid bar after the opening backticks or start the diagram with bar chart. The fence selects the Mermaid renderer; xychart-beta selects the diagram type in mdview's bundled Mermaid version; bar defines a data series inside that diagram. A fence labeled markdown will display the source rather than draw the chart.
If you save the diagram as a standalone .mmd file, keep only the diagram source, beginning with the chart identifier. The surrounding backticks belong to Markdown documents. For other version differences, see Mermaid rendering compatibility.
xychart Versus xychart-betaBoth identifiers refer to Mermaid's XY chart. Which one works depends on the Mermaid version built into the viewer:
xychart
x-axis [A, B, C]
bar [10, 20, 15]Use xychart with current Mermaid releases. Use xychart-beta when the destination still runs an older release that introduced the diagram under its beta name. Changing the identifier does not change the categories or series syntax.
If a working chart becomes a raw code block after publishing, check the destination's Mermaid version before rewriting the data. A Markdown preview and its final publishing platform may bundle different Mermaid releases.
Recent Mermaid releases can display values on bars through showDataLabel configuration. That option is not available in every deployed renderer. For a portable technical document, include the exact values in a compact table below the chart instead of relying on labels that may disappear after publishing.
| Environment | Builds |
|---|---|
| Development | 72 |
| Staging | 34 |
| Production | 18 |
Because renderer versions vary, preview the chart wherever the Markdown will ultimately be read. A platform with an older Mermaid release may require xychart-beta or ignore newer configuration options.
An XY chart can contain a bar series and line series together:
This is useful for showing actual values against a threshold or target. Explain both series in the surrounding prose because not every renderer provides a detailed legend, and color alone should not carry the meaning.
An XY chart can contain more than one bar statement. Each series must use the same x-axis categories:
Describe the series in nearby prose because legend and color behavior varies by renderer. If readers must distinguish several named series precisely, include the source table below the chart.
Mermaid XY charts do not provide the same control as a dedicated charting library. In particular, do not assume that multiple bar statements will create grouped or stacked bars: series can overlap at the same category positions. If readers need to compare every value precisely, use a source table or a dedicated charting tool that supports the required layout.
Add horizontal after the chart identifier to turn the category comparison sideways:
The values still correspond to the categories in order: Web API has 12 incidents, Job Queue has 7, and Data Store has 4. Horizontal bars give longer category names more room. Current Mermaid documentation uses xychart horizontal; this example keeps xychart-beta for mdview's bundled renderer. Check the official XY chart syntax when targeting a different version.
A frequency chart uses the same syntax. Categories represent ranges and values represent counts:
Keep ranges mutually exclusive and state the unit. Mermaid does not calculate bins from raw observations; prepare the frequency counts before placing them in the chart.
Quote category labels containing spaces:
Short labels work best. If categories require full sentences, use a table or explain abbreviations below the chart. A narrow reading column cannot make ten long labels readable merely because the syntax is valid.
Starting a bar chart above zero can visually exaggerate differences. For ordinary comparisons, use zero as the lower bound:
y-axis "Latency (ms)" 0 --> 500Set the upper bound slightly above the largest value so the tallest bar has room. Choose units in the axis title—requests, milliseconds, percent, or dollars—rather than forcing readers to infer them.
For percentages, make the scale explicit from zero to 100. Mermaid treats the values as ordinary numbers; the % meaning comes from the axis label and surrounding explanation.
The same pattern works for prices, scores, and other category comparisons. Put the unit in the y-axis label, keep category and value counts equal, and use a table below the chart when readers need exact currency symbols or decimal values.
Mermaid Gantt diagrams also use horizontal bars, but they represent tasks across time. Use xychart when comparing numeric categories such as services, regions, or monthly totals. Use gantt when bar position and length describe a schedule.
If the chart does not render, check these points:
mermaid, not markdown or text.xychart-beta on mdview.io today, or xychart in current Mermaid documentation.A basic Markdown renderer may display the entire block as code even when the syntax is correct. Open it in mdview.io to render the bar chart inside the document and check it beside the table or explanation it supports.
A chart communicates shape; a table communicates exact values. For reports and technical decisions, consider placing a small source table below the chart. Readers can verify exact numbers, the chart remains accessible when diagram rendering is unavailable, and future editors have a clear record of what each bar represents.
Stacking is not portable across Mermaid versions and renderers. Treat multiple bar statements as separate series, then verify the rendered result. Use a table or dedicated charting tool when a true stacked layout is required.
Yes. Add horizontal after the chart identifier, as in xychart-beta horizontal in the example above. Test the final destination and keep a source table when compatibility matters.
xychart work in one viewer but not another?The viewers probably bundle different Mermaid versions. Try the identifier supported by the destination—xychart in current releases or xychart-beta in older ones—and test the final published document.
For a numeric comparison, use an XY chart rather than a flowchart with bar-shaped nodes. Keep one category per value, put units in the y-axis label, and use a zero baseline for ordinary bar comparisons. Before adding a second series, test one series in the destination renderer.
If the document needs task durations instead of numeric categories, use the Gantt examples. For grouping flowchart nodes, use subgraphs. These are different diagram structures, not alternate bar chart syntax.