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

> Implement ARIA accessibility for ECharts charts easily. Enable the ARIA component to automatically generate screen-reader descriptions and apply essential attributes for improved chart access.

- Repository: [The Apache Software Foundation/echarts](https://github.com/apache/echarts)
- Tags: how-to-guide
- Published: 2026-03-04

---

**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`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/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:

```javascript
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`](https://github.com/apache/echarts/blob/main/i18n/langEN.js). The default English templates follow this structure:

```javascript
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:

```javascript
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:

```javascript
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:

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

```

When `decal.show` is `true`, the visual stage in [`src/visual/aria.ts`](https://github.com/apache/echarts/blob/main/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:

```javascript
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:

```html
<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`](https://github.com/apache/echarts/blob/main/src/component/aria/preprocessor.ts) and [`src/visual/aria.ts`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/src/component/aria/preprocessor.ts) and the visual handler in [`src/visual/aria.ts`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/src/component/aria/preprocessor.ts) normalizes user options and handles legacy field migration. [`src/visual/aria.ts`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/src/component/aria/install.ts) registers both stages with the ECharts extension system. Locale-specific templates reside in files like [`i18n/langEN.js`](https://github.com/apache/echarts/blob/main/i18n/langEN.js).