Skip to main content

ECharts

npm GitHub

Apache ECharts is a powerful JavaScript charting and data visualization library with a large chart-type catalog, responsive canvas and SVG rendering, built-in interactions, and a flexible option-based API. See the ECharts handbook and ECharts option documentation for the underlying chart API.

The echarts-extension-chart2music extension adds Chart2Music directly to an ECharts instance. It derives the chart title, chart type, data, axes, and visual focus synchronization from the ECharts option, so you do not call c2mChart yourself.

The extension 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 echarts-extension-chart2music Storybook examples for interactive examples of the supported chart types and extension options.

Install​

npm install echarts echarts-extension-chart2music

Register the extension​

Register the extension with ECharts before creating charts that should use Chart2Music.

import * as echarts from "echarts/core";
import { BarChart } from "echarts/charts";
import {
  GridComponent,
  TitleComponent,
  TooltipComponent,
} from "echarts/components";
import { CanvasRenderer } from "echarts/renderers";
import echarts2music, { connect } from "echarts-extension-chart2music";

echarts.use([
  BarChart,
  GridComponent,
  TitleComponent,
  TooltipComponent,
  CanvasRenderer,
  echarts2music,
]);

const chart = echarts.init(document.getElementById("sales-chart"));

chart.setOption({
  title: {
    text: "Monthly sales",
  },
  tooltip: {},
  xAxis: {
    type: "category",
    name: "Month",
    data: ["January", "February", "March"],
  },
  yAxis: {
    type: "value",
    name: "Sales",
  },
  series: [
    {
      type: "bar",
      data: [12, 19, 8],
    },
  ],
});

const music = connect(chart);

Use the full ECharts bundle​

If your application imports the full ECharts bundle, register the extension before calling setOption.

import * as echarts from "echarts";
import echarts2music, { connect } from "echarts-extension-chart2music";

echarts.use([echarts2music]);

const chart = echarts.init(document.getElementById("sales-chart"));

chart.setOption({
  title: {
    text: "Monthly sales",
  },
  tooltip: {},
  xAxis: {
    type: "category",
    name: "Month",
    data: ["January", "February", "March"],
  },
  yAxis: {
    type: "value",
    name: "Sales",
  },
  series: [
    {
      type: "line",
      data: [12, 19, 8],
    },
  ],
});

const music = connect(chart);

Extension options​

Pass Chart2Music options to connect. The cc, audioEngine, and axes options correspond to their Chart2Music counterparts. Use errorCallback to receive extension errors and lang to choose a supported Chart2Music language.

chart.setOption({
  title: {
    text: "Monthly sales",
  },
  tooltip: {},
  xAxis: {
    type: "category",
    name: "Month",
    data: ["January", "February", "March"],
  },
  yAxis: {
    type: "value",
    name: "Sales in US dollars",
  },
  series: [
    {
      type: "bar",
      data: [1200, 1900, 1500],
    },
  ],
});

const music = connect(chart, {
  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. In ECharts, set name on each axis so the extension can use that text for accessibility.

chart.setOption({
  title: {
    text: "Monthly sales",
  },
  tooltip: {},
  xAxis: {
    type: "category",
    name: "Month",
    data: ["January", "February", "March"],
  },
  yAxis: {
    type: "value",
    name: "Sales in US dollars",
  },
  series: [
    {
      type: "line",
      data: [1200, 1900, 1500],
    },
  ],
});

const music = connect(chart);

Supported chart types​

The extension is in beta. Currently, the following chart types are supported:

  • Bar
  • Boxplot
  • Candlestick
  • Funnel
  • Heatmap
  • Line
  • Pie
  • Scatter
  • Hierarchy charts