How to Implement ARIA Accessibility Attributes for ECharts Charts: A Complete Guide

Enable the ARIA component by setting aria.enabled: true in your chart options to automatically generate screen-reader-friendly descriptions and apply accessibility attributes to the chart container.

Apache ECharts provides a built-in ARIA component that makes data visualizations accessible to assistive technologies. By implementing ARIA accessibility attributes for ECharts charts, you ensure that screen readers can convey meaningful information about your data to visually impaired users without requiring manual DOM manipulation.

How the ECharts ARIA Component Works

The ARIA implementation follows a three-stage pipeline defined in the apache/echarts source code. Understanding this architecture helps you debug accessibility issues and customize behavior effectively.

The Preprocessor Stage

Located in src/component/aria/preprocessor.ts, this stage normalizes user configuration and handles backward compatibility. It migrates legacy fields such as description, general, series, and data into the modern option.aria.label structure. It also maps the deprecated aria.show flag to the current aria.enabled property.

The Visual Stage

The core logic resides in src/visual/aria.ts. After the chart model is built, this component:

1. Merges default ARIA configuration with locale-specific strings from i18n/langEN.js (or your active locale)
2. Generates a descriptive string using chart metadata, series types, and data values
3. Applies role="img" to the chart container
4. Sets the aria-label attribute via dom.setAttribute('aria-label', ariaLabel)
5. Optionally injects decal patterns for color-blind accessibility when aria.decal.show is enabled

The Installation Stage

The src/component/aria/install.ts file registers both the preprocessor and visual stages with ECharts' extension system using registerPreprocessor and registerVisual.

Enabling ARIA Accessibility in Your Charts

ARIA is disabled by default to optimize rendering performance. To activate accessibility features, explicitly enable the component in your chart configuration:

const chart = echarts.init(document.getElementById('main'));
chart.setOption({
    // ... your chart data and series configuration ...
    aria: {
        enabled: true  // Use `show: true` for ECharts versions prior to 5.0
    }
});

Once enabled, ECharts automatically generates appropriate ARIA attributes without requiring additional DOM manipulation.

Customizing ARIA Labels and Descriptions

Overriding Default Templates

ECharts constructs ARIA labels using template strings defined in locale files such as i18n/langEN.js. The default English templates follow this structure:

aria: {
    general: {
        withTitle: 'This is a chart about "{title}"',
        withoutTitle: 'This is a chart'
    },
    series: {
        single: {
            prefix: '',
            withName: ' with type {seriesType} named {seriesName}.',
            withoutName: ' with type {seriesType}.'
        },
        multiple: {
            prefix: '. It consists of {seriesCount} series count.',
            withName: ' The {seriesId} series is a {seriesType} representing {seriesName}.',
            withoutName: ' The {seriesId} series is a {seriesType}.',
            separator: { middle: '', end: '' }
        }
    },
    data: {
        allData: 'The data is as follows: ',
        partialData: 'The first {displayCnt} items are: ',
        withName: 'the data for {name} is {value}',
        withoutName: '{value}',
        separator: { middle: ', ', end: '. ' }
    }
}

You can override any template by providing a label object in your aria configuration:

chart.setOption({
    aria: {
        enabled: true,
        label: {
            general: {
                withTitle: 'Chart titled "{title}" displaying sales metrics.'
            },
            series: {
                single: {
                    withName: ' showing {seriesType} data for {seriesName}.'
                }
            }
        }
    }
});

Using Static Descriptions

For maximum control, provide a static description string. When present, ECharts skips automatic template generation and uses your text verbatim:

aria: {
    enabled: true,
    label: {
        description: 'Bar chart showing quarterly revenue growth of 15% year over year.'
    }
}

Adding Decal Patterns for Color-Blind Accessibility

The ARIA component supports decal patterns that add texture overlays to chart elements, making them distinguishable for users with color vision deficiencies. Enable this feature through the decal property:

chart.setOption({
    aria: {
        enabled: true,
        decal: { show: true }
    }
});

When decal.show is true, the visual stage in src/visual/aria.ts iterates over each series, generates patterns from the global decal palette using getDecalFromPalette(), and merges them with any user-specified decals. Series that implement enableAriaDecal() can customize how patterns are applied to their specific rendering geometry.

Complete Implementation Example

The following example demonstrates a fully accessible ECharts configuration with custom labels and decal patterns:

import * as echarts from 'echarts';

const myChart = echarts.init(document.getElementById('chart'));

myChart.setOption({
    title: {
        text: 'Quarterly Sales'
    },
    tooltip: {},
    legend: { data: ['2019', '2020'] },
    xAxis: { type: 'category', data: ['Q1', 'Q2', 'Q3', 'Q4'] },
    yAxis: { type: 'value' },
    series: [
        { name: '2019', type: 'bar', data: [120, 200, 150, 80] },
        { name: '2020', type: 'bar', data: [90, 160, 130, 70] }
    ],
    aria: {
        enabled: true,
        label: {
            description: 'Bar chart showing quarterly sales for 2019 and 2020.',
            general: {
                withTitle: 'Chart titled "{title}" displaying sales.'
            },
            series: {
                multiple: {
                    prefix: '. It contains {seriesCount} series.',
                    withName: ' Series {seriesId} ({seriesName}) is a {seriesType}.'
                }
            },
            data: {
                allData: 'Values are: ',
                withName: '{name}: {value}'
            }
        },
        decal: { show: true }
    }
});

This configuration produces a DOM element with accessibility attributes similar to:

<div role="img" aria-label="This is a chart about &quot;Quarterly Sales&quot;. It contains 2 series. Series 0 (2019) is a bar. Series 1 (2020) is a bar. Values are: Q1: 120, Q2: 200, Q3: 150, Q4: 80.">

Screen readers will announce the chart structure and data values, ensuring visually impaired users can comprehend the visualization without seeing it.

Summary

• ARIA is opt-in: Set aria.enabled: true in your chart options to activate accessibility features in src/component/aria/preprocessor.ts and src/visual/aria.ts.
• Automatic label generation: The component constructs descriptions from chart titles, series types, and data values using templates defined in locale files like i18n/langEN.js.
• Custom descriptions: Override templates via option.aria.label or provide a static description string for full control over screen reader text.
• Color-blind support: Enable aria.decal.show: true to add texture patterns that distinguish series without relying solely on color.
• DOM attributes: The implementation automatically applies role="img" and aria-label to the chart container, requiring no manual DOM manipulation.

Frequently Asked Questions

Is ARIA enabled by default in ECharts?

No, ARIA accessibility features are disabled by default to optimize rendering performance. You must explicitly set aria.enabled: true (or aria.show: true in older versions) in your chart configuration to activate the preprocessor in src/component/aria/preprocessor.ts and the visual handler in src/visual/aria.ts.

How do I provide a custom description for screen readers?

You can customize screen reader descriptions in two ways. First, provide a static description string in option.aria.label.description, which bypasses automatic generation entirely. Second, override specific template strings such as general.withTitle or series.single.withName to customize how the automatic description is constructed from chart metadata.

What are decal patterns and when should I use them?

Decal patterns are texture overlays (such as hatching or dots) applied to chart series when you set aria.decal.show: true. According to the implementation in src/visual/aria.ts, these patterns are generated from the global decal palette and help users with color vision deficiencies distinguish between data series that might otherwise rely solely on color differences. Use them when your chart uses multiple series with similar hues or when accessibility compliance requires color-independent differentiation.

Which ECharts source files handle ARIA processing?

The ARIA subsystem spans three main files in the apache/echarts repository. src/component/aria/preprocessor.ts normalizes user options and handles legacy field migration. src/visual/aria.ts contains the core logic for generating aria-label strings, applying role="img", and managing decal patterns. src/component/aria/install.ts registers both stages with the ECharts extension system. Locale-specific templates reside in files like i18n/langEN.js.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}