Skip to main content

Chart.js

npm GitHub

The chartjs-plugin-chart2music plugin adds Chart2Music directly to a Chart.js chart. It derives the chart title, chart type, data, axes, and visual focus synchronization from the Chart.js configuration, so you do not call c2mChart yourself.

The plugin makes the chart keyboard navigable and sonified, updates the visual focus as users explore data, and adapts the chart element for screen-reader users.

See the chartjs2music Storybook examples for interactive examples of the supported chart types and plugin options.

Install​

npm install chart.js chartjs-plugin-chart2music

Register globally​

Register the plugin once to enable it for every Chart.js chart on the page or in your application.

import { Chart } from "chart.js/auto";
import chartjs2music from "chartjs-plugin-chart2music";

Chart.register(chartjs2music);

new Chart(document.getElementById("sales-chart"), {
  type: "bar",
  data: {
    labels: ["January", "February", "March"],
    datasets: [{ label: "Sales", data: [12, 19, 8] }],
  },
  options: {
    plugins: {
      title: {
        display: true,
        text: "Monthly sales",
      },
    },
  },
});

Register for one chart​

Add the plugin to a chart's plugins array when only selected charts need Chart2Music.

import { Chart } from "chart.js/auto";
import chartjs2music from "chartjs-plugin-chart2music";

new Chart(document.getElementById("sales-chart"), {
  type: "line",
  data: {
    labels: ["January", "February", "March"],
    datasets: [{ label: "Sales", data: [12, 19, 8] }],
  },
  plugins: [chartjs2music],
  options: {
    plugins: {
      title: {
        display: true,
        text: "Monthly sales",
      },
    },
  },
});

Plugin options​

Configure Chart2Music under options.plugins.chartjs2music. The cc, audioEngine, and axes options correspond to their Chart2Music counterparts. Use errorCallback to receive plugin errors and lang to choose a supported Chart2Music language.

new Chart(document.getElementById("sales-chart"), {
  type: "bar",
  data: {
    labels: ["January", "February", "March"],
    datasets: [{ label: "Sales", data: [1200, 1900, 1500] }],
  },
  plugins: [chartjs2music],
  options: {
    plugins: {
      chartjs2music: {
        cc: document.getElementById("chart-status"),
        errorCallback: console.error,
        lang: "en",
        axes: {
          y: { format: (value) => `$${value.toLocaleString()}` },
        },
      },
    },
  },
});

Label both axes​

Always provide labels for x- and y-axes. Axis labels give screen reader users the context needed to understand a value. You can suppress labels visually without removing them from the chart configuration; the plugin can still use their text for accessibility.

new Chart(document.getElementById("sales-chart"), {
  type: "line",
  data: {
    labels: ["January", "February", "March"],
    datasets: [{ label: "Sales", data: [1200, 1900, 1500] }],
  },
  plugins: [chartjs2music],
  options: {
    scales: {
      x: {
        title: {
          display: false,
          text: "Month",
        },
      },
      y: {
        title: {
          display: false,
          text: "Sales in US dollars",
        },
      },
    },
  },
});

Supported chart types​

The plugin is in beta. It supports these built-in Chart.js types:

  • Bar
  • Doughnut
  • Line
  • Pie
  • Polar area
  • Radar
  • Scatter
  • Mixed charts composed of the supported types

It also supports these types when their Chart.js companion plugin is registered:

chartjs-chart-matrix is not currently supported by chartjs-plugin-chart2music; matrix support is planned. Other currently unsupported companion plugins include error bars, parallel coordinates, and zoom.

Accessible dataset toggles​

chartjs-plugin-a11y-legend complements Chart2Music by giving keyboard-only and screen-reader users an accessible legend for toggling data groups on and off. Register it alongside Chart2Music:

import { Chart } from "chart.js/auto";
import chartjs2music from "chartjs-plugin-chart2music";
import a11yLegend from "chartjs-plugin-a11y-legend";

Chart.register(chartjs2music, a11yLegend);

When using the plugins together, test the legend behavior with your chart configuration. Dataset visibility updates are a planned area of support in the Chart2Music plugin.