Mermaid Bar Chart: Markdown Syntax and Copyable Examples

Markdown tables are excellent for exact values, but a Mermaid bar chart makes comparisons visible immediately. The chart stays as editable text inside the same .md file: change the labels or values in the fenced block and render the document again.

Mermaid Bar Chart Example

Copy this working Markdown example. The mermaid fence tells a compatible viewer to render the code as a chart:

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 five days, the bar series should contain five numbers.

xychart Versus xychart-beta

Both 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.

Showing Exact Values

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.

Combining Bars and a Line

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.

Multiple Bar Series

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 a portable stacked chart. Current Mermaid releases support horizontal orientation through XY-chart configuration, but older embedded renderers may ignore it. Verify the exact Mermaid version you publish to; when portability matters, use grouped vertical bars, a table, or a purpose-built chart image with accessible source data.

For a current renderer, horizontal orientation can be requested in the diagram frontmatter:

---
config:
    xyChart:
        chartOrientation: horizontal
---
xychart
    title "Incidents by service"
    x-axis ["Web API", "Job Queue", "Data Store"]
    y-axis "Incidents" 0 --> 20
    bar [12, 7, 4]

If the chart remains vertical or fails to render, the destination likely bundles a Mermaid version from before this configuration was available.

Frequency Bar Chart Example

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.

Labels With Spaces

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.

Choosing the Y-Axis Range

Starting a bar chart above zero can visually exaggerate differences. For ordinary comparisons, use zero as the lower bound:

y-axis "Latency (ms)" 0 --> 500

Set 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.

Percentage and Category Bar Charts

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.

Bar Chart or Gantt Chart?

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.

Common Rendering Problems

If the chart does not render, check these points:

1. The fence is labeled mermaid, not markdown or text.
2. The first diagram line matches the Mermaid version: xychart-beta on mdview.io today, or xychart in current Mermaid documentation.
3. Categories are enclosed in square brackets.
4. The bar values are numeric and comma-separated.
5. The category and value counts match.
6. Labels containing spaces are quoted.
7. The target viewer supports Mermaid XY charts.
8. Every series contains the same number of values as the x-axis.

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.

Keep the Data Auditable

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.

Mermaid Bar Chart FAQ

Can Mermaid create a stacked bar chart?

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.

Can Mermaid create a horizontal bar chart?

Current Mermaid XY charts support chartOrientation: horizontal in diagram configuration. Older embedded renderers may ignore or reject it, so test the final destination and keep a source table when compatibility matters.

Why does 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.