Getting Started

Magma charts enable you to convey precise and compelling narratives around data through visually appealing and accessible visualizations. 

Magma Charts is based on Carbon Charts from IBM.

Get started below with implementation instructions for developers. You can also learn more about the chart types we provide, as well as view examples.

Installation

Setup Requirements

Your project needs to be running React v17

Install the Charts Library

Install the React Magma Charts library with npm.

npm install --save @react-magma/charts

Install peer dependencies

npm install --save \
    "@emotion/react@^11.13.0" \
    "@emotion/styled@^11.13.0" \
    "react@^17.0.2" \
    "react-dom@^17.0.2" \
    "react-magma-dom@^4.7.0-next.1" \
    "react-magma-icons@^3.0.0" \
    "@react-magma/charts@^9.0.0"

Accessible chart toolbar

Carbon Charts ships with built-in toolbar buttons (Show as Table, Fullscreen, More Options) that have several WCAG 2.2 violations:

• aria-haspopup="true" is used incorrectly (it should be "dialog" for the table button and absent on the fullscreen button)
• Focus does not move into the modal when "Show as Table" is activated
• The table dialog lacks a semantic heading
• The chart title uses <p role="heading"> instead of a semantic heading element
• Screen readers announce button labels redundantly
• The "Show as table" label is not descriptive enough

The chartToolbar prop on CarbonChart replaces Carbon's toolbar with accessible Magma components. When provided, Carbon's built-in toolbar is automatically disabled and the chart title is rendered as a semantic heading. It defaults to <h2> and can be configured from <h1> through <h6> with chartToolbar.titleLevel.

Basic usage

Pass a chartToolbar object to CarbonChart. The title is read from options.title. This renders the accessible toolbar with "Show as table", "Fullscreen", and "More options" buttons. The "More options" dropdown includes built-in "Download as CSV", "Download as PNG", and "Download as JPG" items.

import React from 'react';

import { CarbonChart, CarbonChartType } from '@react-magma/charts';
import { Card } from 'react-magma-dom';

export function Example() {
  return (
    <Card style={{ padding: '12px' }}>
      <CarbonChart
        type={CarbonChartType.donut}
        dataSet={[
          { group: 'High performance', value: 50 },
          { group: 'Average performance', value: 30 },
          { group: 'Poor performance', value: 15 },
          { group: 'Not attempted', value: 5 },
        ]}
        options={{
          title: 'Overall Activity Performance',
          resizable: true,
          height: '400px',
          donut: {
            center: { label: 'Questions' },
          },
          legend: {
            truncation: { type: 'none' },
          },
        }}
        chartToolbar={{}}
      />
    </Card>
  );
}

See Chart Demos for examples of every chart type with the accessible toolbar enabled, and the Toolbar customization section for advanced configurations (custom menu items, table columns, chart title heading level, custom content around the title and between the title and the chart, button visibility, inverse theme).

Content between the title and the chart

additionalContent is a prop on CarbonChart itself rather than on chartToolbar. It renders below the toolbar row and above the chart, which is where interactive controls such as filters belong — the title row only has space for inline content the height of an icon.

It requires chartToolbar, changes how the chart's total height is composed, and needs options.height set. See Custom content between the title and the chart for the reasoning and a working example.

Chart toolbar props

The chart title is read from options.title (the standard Carbon Charts title option) and rendered as a semantic heading element, replacing Carbon's inaccessible <p role="heading">. It defaults to <h2>; set titleLevel to match the surrounding page hierarchy.

Standalone components

For adopters who need more granular control outside of CarbonChart, the following components are also exported from @react-magma/charts:

• ChartTableButton — Accessible "Show as table" trigger with aria-haspopup="dialog"
• ChartFullscreenButton — Fullscreen toggle (no aria-haspopup)
• ChartMoreOptionsButton — Dropdown wrapper with MoreVertIcon
• ChartTableModal — Focus-trapped modal with semantic heading, data table, and "Download as CSV" button
• ChartDataTable — Renders chart data in a Magma Table with auto-derived columns
• ChartToolbar — Flex layout wrapper with heading and action slot

Accessibility

The toolbar addresses the following WCAG 2.2 guidelines:

• 1.3.1 Info and Relationships (Level A) — Chart title uses a semantic <h1>–<h6> (default <h2>) instead of <p role="heading">. Modal has a semantic heading. Table uses <th> elements.
• 2.4.3 Focus Order (Level A) — Focus moves into the modal when it opens, and returns to the trigger button when it closes.
• 2.4.6 Headings and Labels (Level AA) — "Show as table" button uses the chart title as its accessible label. Button labels are descriptive and unique.
• 4.1.2 Name, Role, Value (Level A) — Correct aria-haspopup="dialog" on the table button. No aria-haspopup on the fullscreen button. aria-expanded reflects modal state.