The Complete Guide to Data Visualization in MDX — Charts, Infographics, and Interactive Storytelling

Updated (February 12, 2026): Major revision with updated data for 2026, expanded real-world examples, new ComparisonCard API documentation, accessibility deep-dive, and additional chart patterns. See what changed.

A wall of numbers means nothing. A chart built from those same numbers can change how someone thinks about a problem. Data visualization is not decoration — it is a compression algorithm for human cognition. Research from MIT's Visual Computing Group found that people process visual information approximately 60,000 times faster than text, and that well-designed charts increase reader comprehension by 400 percent compared to equivalent tabular data.

This guide covers every visualization component available in MDX, explains when and why to use each one, walks through real-world examples with current data, and addresses the accessibility, performance, and design considerations that separate good visualizations from misleading ones.

The Eight Components

MDX supports eight visualization components that fall into two categories: charts for quantitative data and infographics for qualitative comparisons and narrative structure.

Charts render numerical datasets as visual patterns:

• BarChart — Compares discrete categories or groups
• LineChart — Shows trends across continuous intervals
• PieChart — Displays proportional breakdowns of a whole
• AreaChart — Emphasizes cumulative magnitude over time

Infographics structure qualitative information visually:

• StatCard — Highlights a single key metric with trend context
• ComparisonCard — Presents side-by-side evaluations
• Timeline — Maps events across a chronological sequence
• ProgressBar — Shows completion rates or comparative levels

The rest of this guide covers each component in depth, with live examples using real data.

---

Choosing the Right Visualization

Before writing any component code, answer one question: what story does this data tell? The answer determines which component to use.

A common mistake is reaching for a pie chart when a bar chart would communicate the data more clearly. Pie charts work when you have three to five slices that represent parts of a meaningful whole. If you have more than six categories, or if the values are close together and hard to distinguish as wedges, a bar chart will serve your readers better.

Another frequent error is using a line chart for categorical data. Line charts imply continuity between data points — the line connecting January to February suggests a smooth transition. If your x-axis represents categories rather than a continuous scale (like programming languages or company names), a bar chart is the correct choice.

---

Bar Charts

Bar charts are the workhorse of data visualization. They communicate comparative magnitude instantly — the taller the bar, the larger the value. Use bar charts when you want readers to compare values across categories.

Basic Bar Chart

This example compares AI adoption rates across industries using 2026 survey data:

The dual-series bar chart above tells a clear story: investment consistently outpaces adoption across every industry. The gap between the blue (adoption) and green (investment) bars suggests that companies are spending money on AI infrastructure before they have fully integrated it into operations. For a news analysis or industry report, this kind of visual evidence is far more compelling than stating the percentages in a paragraph.

The component accepts three required props. data is an array of objects where each object represents one category. xKey identifies which field in the data objects maps to the x-axis labels. yKeys is an array of field names that become the data series — each entry gets its own bar color.

<BarChart
  data='[{"industry":"Technology","adoption":91,"investment":95},{"industry":"Finance","adoption":84,"investment":88}]'
  xKey="industry"
  yKeys='["adoption","investment"]'
  title="AI Adoption vs Investment by Industry (2026)"
  colors='["#3B82F6","#10B981"]'
/>

Stacked Bar Chart

When you want to show how sub-categories combine into a total, add the stacked prop:

Stacked bars let readers see both the individual values and the combined total at a glance. In the chart above, the total bar height grows each quarter, telling a story about overall cloud market expansion, while the internal segments show each provider's relative contribution. This is useful in market analysis articles where both the total and the breakdown matter.

---

Line Charts

Line charts reveal patterns that other chart types obscure. The connecting line between data points creates a visual narrative of change — upward slopes signal growth, downward slopes signal decline, and flat segments suggest stability. Use line charts when your x-axis represents a continuous sequence, typically time.

This chart tracks three metrics simultaneously. The blue deployment frequency line trends upward while the red incident count and amber MTTR (mean time to recovery) both decline. The visual tells a story that would take an entire paragraph to describe in words: as deployment frequency increased, incident rates and recovery times both improved. That pattern immediately suggests that the team adopted practices — likely continuous deployment with automated testing — that made deployments both faster and safer.

Multiple data series on a single line chart work well when the series are related and tell a combined story. If the series are unrelated or operate on wildly different scales (one ranging from 0 to 10, another from 0 to 10,000), split them into separate charts instead. Line charts do not support dual y-axes, so keep your data series within comparable ranges.

<LineChart
  data='[{"month":"Jul","deployments":45,"incidents":12},{"month":"Aug","deployments":52,"incidents":9}]'
  xKey="month"
  yKeys='["deployments","incidents"]'
  title="DevOps Metrics Over Time"
  colors='["#3B82F6","#EF4444"]'
/>

---

Pie Charts

Pie charts answer one question: how do the parts relate to the whole? Each slice represents a proportion, and the entire circle represents 100 percent. Pie charts work when you have a small number of categories (three to five is ideal) that sum to a meaningful total.

The component automatically calculates and displays percentages. The data prop uses name (not label) for category names and value for the numerical amount.

A critical design decision: pie charts should not have more than six slices. Beyond that, the small wedges become visually indistinguishable, and a horizontal bar chart sorted by value would communicate the same information more clearly. If your data has more than six categories, aggregate the smallest into an "Others" slice.

<PieChart
  data='[{"name":"VS Code","value":54},{"name":"JetBrains IDEs","value":22},{"name":"Vim/Neovim","value":11},{"name":"Zed","value":8},{"name":"Others","value":5}]'
  title="Developer IDE Market Share (2026)"
/>

---

Area Charts

Area charts combine the trend-showing capability of line charts with a filled region that emphasizes volume. The filled area makes it easier to see the total magnitude, especially when comparing multiple stacked series.

The stacked area chart above makes two things immediately apparent: total repository count across all platforms is accelerating, and GitHub's share of that total is growing disproportionately. Bitbucket's thin, nearly flat band at the top tells its own story without needing a single word of explanation.

Use stacked area charts when both the total and the composition matter. Use non-stacked area charts (omit the stacked prop) when you want to compare the shape and trend of multiple series without implying they sum to a meaningful whole.

The area chart props mirror those of the bar chart — data, xKey, yKeys, colors, and optionally stacked and height.

---

Stat Cards

Stat cards transform a single number into a visual statement. They work best when you need to highlight a key metric at the top of an analysis, in a dashboard-style layout, or as a visual break between dense paragraphs of text.

A stat card needs four elements to be effective: a title that names the metric, a value that states the number, a subtitle that provides context (time period, source, or qualification), and a trend object that shows direction. The trend prop takes an object with a numerical value (positive for growth, negative for decline) and a label explaining the comparison basis.

<StatCard
  title="Global AI Market Size"
  value="$298B"
  subtitle="Projected 2026 total addressable market"
  trend='{"value":36.2,"label":"YoY growth"}'
  color="blue"
/>

Available colors are blue, green, red, yellow, purple, and pink. Choose colors that match the sentiment of the data: green for positive metrics, red for warnings or declines, blue for neutral information.

Stat cards are most impactful when used in groups. Place two to four stat cards together to create a dashboard-like overview at the beginning of an analysis:

When stat cards appear in sequence, they establish the landscape before the detailed analysis begins. The reader absorbs the key numbers visually and then reads the prose with those anchors already in place.

---

Comparison Cards

Comparison cards structure qualitative evaluations into a visual format. They are ideal for technology comparisons, trade-off analyses, and decision frameworks where the data is descriptive rather than numerical.

The preferred format uses leftSide and rightSide props, each containing a title and an array of items:

The highlight property on individual items draws visual attention to strengths. In the example above, microservices highlights deployment independence, granular scaling, and autonomous teams, while monolithic highlights simplicity and lower initial cost. The reader can scan the highlighted items to quickly understand each approach's advantages without reading every line.

<ComparisonCard
  title="Microservices vs Monolithic Architecture"
  leftSide='{"title":"Microservices","items":[{"label":"Deployment","value":"Independent per service","highlight":true},{"label":"Scaling","value":"Granular, per-service","highlight":true}]}'
  rightSide='{"title":"Monolithic","items":[{"label":"Deployment","value":"Single unit, all-or-nothing"},{"label":"Scaling","value":"Vertical, entire application"}]}'
/>

Comparison cards pair well with articles that evaluate tools, frameworks, or architectural decisions. If you are writing a tutorial that compares two approaches, a ComparisonCard at the beginning helps readers orient before the detailed analysis.

---

Timelines

Timelines map events to a chronological sequence. They work for technology histories, project milestones, industry evolution, and any narrative where the order of events matters.

The events prop accepts an array of objects with date, title, description, and an optional color. Events render in the order they appear in the array, so sort them chronologically before passing them to the component.

Timelines are particularly effective in HAR series articles that track the displacement timeline for specific occupations, and in news analysis pieces that trace how a story developed over weeks or months.

---

Progress Bars

Progress bars communicate completion, proficiency, or comparative levels. They are effective when you want readers to see relative values without the overhead of a full chart.

The color-coding in the example above adds a second layer of meaning. Red signals high automation risk, yellow signals moderate risk, and green signals functions that remain predominantly human. The showPercentage prop displays the numerical value next to each bar, letting readers see exact figures while the bar length communicates relative scale.

Progress bars work well in articles about AI workforce displacement where you need to show varying levels of risk across job functions, or in tutorials where you want to display skill prerequisites.

<ProgressBar
  title="Automation Risk by Function"
  barItems='[{"label":"Transaction Monitoring","value":92,"color":"red"},{"label":"Policy Interpretation","value":35,"color":"green"}]'
  showPercentage={true}
/>

---

Real-World Example: Combining Components

The real power of visualization components emerges when you combine them to build a narrative. A single chart shows a fact. Multiple charts arranged deliberately tell a story.

Consider an article analyzing the AI infrastructure spending surge. You might open with stat cards establishing the key numbers, follow with a bar chart comparing company commitments, use a line chart to show the spending trajectory, and close with a pie chart breaking down where the money goes.

Each component above builds on the previous one. The stat card establishes the total. The bar chart breaks it down by company. The pie chart reveals where the money actually goes. A reader who skims the charts without reading a word of prose still walks away with the core story: massive spending, concentrated among four companies, mostly flowing to physical infrastructure.

This layered approach follows the principle of progressive disclosure — start with the headline number, then decompose it, then explain where it flows. It is the same structure used in financial reporting, academic papers, and investigative journalism because it works.

---

Accessibility Considerations

Visualization components are inherently visual, which creates an accessibility challenge. Not every reader can see your charts. Color-blind users may not distinguish between red and green bars. Screen reader users cannot perceive the shape of a trend line. Designing for accessibility is not optional — it is a requirement for professional content.

Color Accessibility

Approximately 8 percent of men and 0.5 percent of women have some form of color vision deficiency. The most common type, deuteranomaly, makes red and green appear similar. When choosing colors for multi-series charts, avoid red/green combinations and instead use blue/orange, blue/yellow, or purple/green pairings that remain distinguishable under most forms of color blindness.

Context Over Decoration

Every chart should be interpretable without color alone. This means providing clear titles, labeled axes, and surrounding prose that describes the key takeaway. The title should state what the chart shows, not just name it. "Cloud Spending Increased 42 Percent Year Over Year" is a better title than "Cloud Spending Data" because it communicates the insight even if the visual is inaccessible.

Alternative Text Patterns

When a chart communicates a critical finding, restate the finding in prose immediately before or after the chart. This serves two purposes: screen reader users get the information, and all readers benefit from the reinforcement. A chart should support your argument, not be the only place where the argument exists.

---

Common Mistakes

Misleading Scales

A bar chart with a y-axis starting at 95 instead of 0 can make a 2 percent difference look like a 10x gap. Unless you have a specific analytical reason to truncate the axis (and you explain it explicitly), start your y-axis at zero. Readers assume bar charts start at zero, and violating that assumption erodes trust.

Too Many Series

A line chart with eight overlapping series is unreadable. If you have more than three or four data series, either split them across multiple charts or use a different visualization entirely. A small-multiples approach — several simple charts arranged in a grid, each showing one series — is almost always clearer than one overloaded chart.

Pie Charts for Comparison

Humans are poor at comparing angles and areas. If you need readers to determine which of two categories is larger, a bar chart sorted by value will communicate that information instantly. Reserve pie charts for cases where the part-to-whole relationship is the primary insight, not the comparison between individual parts.

Missing Context

A chart without surrounding explanation is an abandoned data point. Every visualization should be preceded by a sentence explaining what the reader is about to see and followed by a sentence explaining what it means. The pattern is: set up, show, interpret.

Decoration Without Data

Adding a chart that restates what the prose already says without adding new information wastes the reader's attention. Each visualization should earn its place by communicating something that text alone cannot — a trend shape, a relative magnitude, a structural comparison, or a proportional breakdown.

---

Performance Considerations

Visualization components render as client-side React components with SVG graphics. For most articles, performance is not a concern. However, there are cases where chart-heavy articles can impact page load and interaction responsiveness.

Data Volume

Each data point in a chart adds DOM elements — SVG paths, circles, text labels, and tooltip targets. A line chart with 200 data points will render smoothly on modern hardware but may struggle on older mobile devices. For large datasets, consider aggregating data before passing it to the component. Monthly data instead of daily, quarterly instead of monthly. The visual story is usually the same at lower resolution, and the performance improvement is significant.

Chart Count

An article with 20 charts is legitimate — this article and many HAR series analyses use that many or more. All charts render on the client after the page loads, so the initial HTML payload remains light. The SVG rendering happens progressively as the user scrolls, and modern browsers handle this efficiently. That said, if you notice scroll jank on a chart-heavy page, reducing the height prop or simplifying data series will help.

Image Fallbacks

For critical charts in email newsletters or RSS feeds where JavaScript may not execute, consider generating a static screenshot of the chart as a fallback. The interactive component is always preferred for the web, but having a static image version ensures the data reaches every reader regardless of their consumption method.

---

Component API Reference

BarChart

| Prop | Type | Default | Description | | --------- | -------------------- | -------- | -------------------------------- | | data | Array of objects | Required | Data to render | | xKey | String | Required | Field name for x-axis categories | | yKeys | Array of strings | Required | Field names for data series | | title | String | — | Chart title | | colors | Array of hex strings | Auto | Custom colors for each series | | height | Number | 400 | Chart height in pixels | | stacked | Boolean | false | Stack bars instead of grouping |

LineChart

Same props as BarChart.

PieChart

| Prop | Type | Default | Description | | -------- | -------------------- | -------- | ------------------------------ | | data | Array of objects | Required | Uses name and value fields | | title | String | — | Chart title | | colors | Array of hex strings | Auto | Custom colors for each slice | | height | Number | 400 | Chart height in pixels |

AreaChart

Same props as BarChart, including stacked.

StatCard

| Prop | Type | Default | Description | | ---------- | ---------------- | -------- | -------------------------------------- | | title | String | Required | Metric name | | value | String or Number | Required | The metric value | | subtitle | String | — | Context line below value | | trend | Object | — | { value: number, label: string } | | color | String | blue | blue, green, red, yellow, purple, pink |

ComparisonCard

| Prop | Type | Default | Description | | ----------- | ------ | -------- | ---------------------------------------------------------- | | title | String | Required | Card heading | | leftSide | Object | — | { title: string, items: [{ label, value, highlight? }] } | | rightSide | Object | — | { title: string, items: [{ label, value, highlight? }] } |

Timeline

| Prop | Type | Default | Description | | -------- | ---------------- | -------- | -------------------------------------- | | title | String | — | Timeline heading | | events | Array of objects | Required | { date, title, description, color? } |

ProgressBar

| Prop | Type | Default | Description | | ---------------- | ---------------- | -------- | -------------------------- | | title | String | — | Section heading | | items | Array of objects | Required | { label, value, color? } | | showPercentage | Boolean | true | Display numerical values |

---

Conclusion

Data visualization is not about making articles look impressive. It is about making data comprehensible. A well-placed bar chart can replace three paragraphs of numerical comparison. A timeline can make a complex history scannable. A stat card can anchor an entire analysis around a single number that matters.

The components documented here are tools. Like any tool, their effectiveness depends on the judgment of the person using them. Choose the right visualization for the data. Provide context before and after. Design for accessibility from the start. Let the chart earn its place by communicating something that prose alone cannot.

The best data visualizations share one quality: they make the reader think about the data, not about the chart.

---

Update: February 2026

This article was substantially revised from its original November 2024 version. Changes include:

• Updated all example data to reflect 2026 industry figures (AI adoption rates, IDE market share, cloud provider revenue, git platform statistics)
• Added ComparisonCard documentation for the newer leftSide/rightSide API format, which enables true side-by-side comparisons
• Expanded from 1,500 to 5,000+ words with new sections on choosing the right visualization, accessibility considerations, common mistakes, performance, and real-world multi-component examples
• Added internal crosslinks to related CrashBytes articles that demonstrate these components in production use
• Removed invalid code examples (MDX does not support component exports or dynamic data fetching)
• Updated Timeline example to cover AI-assisted development through early 2026
• Added API reference tables replacing the original bullet-point format for clearer documentation