ARIA support in Apache ECharts
Apache ECharts supports the W3C WAI-ARIA (Accessible Rich Internet Applications Suite) specification to make charts accessible to people using screen readers. ECharts 4 generates intelligent descriptions based on chart configuration. ECharts 5 adds support for decal textures as an auxiliary expression of color to further differentiate data. ARIA is turned off by default and must be enabled by setting aria.enabled to true.
aria.enabled option default
The aria.enabled option is a boolean with a default value of false. When false, the label and decal effects are not applied.
aria.label option behavior
When aria.enabled is set to true, aria.label is enabled by default. When enabled, the description of the chart is automatically and intelligently generated based on the chart, data, title, and other configuration items. Users can modify the description through configuration items. The generated description is stored in the aria-label attribute of the chart DOM element.
aria.label.enabled default
The aria.label.enabled option is a boolean with a default value of true. When true and aria.enabled is also true, an accessibility description is generated and the aria-label attribute is set on the chart DOM.
aria.label.description option
The aria.label.description option is a string with a default value of null. If defined, it is used as the full description of the chart instead of the auto-generated description. This allows complete customization of the accessibility description, useful when the auto-generated description is not accurate or does not convey the author's intent.
aria.label.general.withTitle template default
The aria.label.general.withTitle option is a string template with a default value of 'This is a chart about "{title}".'. It is used when the chart has a title.text value. The template variable {title} is replaced with the chart title text.
aria.label.general.withoutTitle template default
The aria.label.general.withoutTitle option is a string template with a default value of 'This is a chart,'. It is used when the chart does not have a title.text value.
aria.label.series.single configuration
When a chart contains only one series, aria.label.series.single configuration is used. It has three sub-options: prefix (default ''), withName (default ' with type {seriesType} named {seriesName}.'), and withoutName (default ' with type {seriesType}.'). The withName template is used if the series has a name attribute, withoutName is used if it does not. Template variables: {seriesCount} (always 1), {seriesName}, {seriesType} (e.g., 'Bar chart', 'Line chart').
aria.label.series.multiple configuration
When a chart contains multiple series, aria.label.series.multiple configuration is used. It has prefix (default '. It consists of {seriesCount} series count.'), withName (default ' The {seriesId} series is a {seriesType} representing {seriesName}.'), withoutName (default ' The {seriesId} series is a {seriesType}.'), and separator sub-options. The withName template is used if the series has a name attribute, withoutName if it does not. Template variables: {seriesCount}, {seriesId}, {seriesType}, {seriesName}.
aria.label.series.multiple.separator configuration
The aria.label.series.multiple.separator has two sub-options: middle (default ';') as the separator between series except after the last series, and end (default '.') as the delimiter after the last series.
aria.label.data.maxCount option
The aria.label.data.maxCount option is a number with a default value of 10. It specifies the maximum number of data items per series included in the accessibility description.
aria.label.data.allData template default
The aria.label.data.allData option is a string template with a default value of 'whose data is --'. It is used in the description when all data is displayed. This option does not cause all data to be displayed; that requires setting aria.label.data.maxCount to Number.MAX_VALUE.
aria.label.data.partialData template default
The aria.label.data.partialData option is a string template with a default value of 'where the first {displayCnt} term is --'. It is used in the description when only partial data is displayed. The template variable {displayCnt} is replaced with the number of data items being displayed.
aria.label.data.withName template default
The aria.label.data.withName option is a string template with a default value of 'The data for {name} is {value}'. It is used for data items that have a name attribute. Template variables: {name} (replaced with the data name), {value} (replaced with the data value).
aria.label.data.withoutName template default
The aria.label.data.withoutName option is a string template with a default value of '{value}'. It is used for data items that do not have a name attribute. Template variable: {value} (replaced with the data value).
aria.label.data.excludeDimensionId option
The aria.label.data.excludeDimensionId option is an array that specifies column indexes to exclude from the data description in aria.label. This option was added in version 5.6.0.
aria.label.data.separator configuration
The aria.label.data.separator has two sub-options: middle (default ',') as the delimiter between data items except the last one, and end (default '') as the delimiter after the last data item. The end is typically an empty string because the series separator.end usually follows.
aria.decal support in ECharts
Decal patterns are added to series data as an additional visual hint beyond color to help differentiate data. Decal patterns are supported in many series types including: line, bar, pie, radar, treemap, sunburst, boxplot, sankey, funnel, gauge, pictorialBar, themeRiver, custom, and others. Some series types without default filling color (line, radar, boxplot) require areaStyle to be set for decals to take effect.
aria.decal.show option default
The aria.decal.show option is a boolean with a default value of false. Decal patterns are not displayed by default. To display decals, both aria.enabled and aria.decal.show must be set to true.
aria.decal.decals option configuration
The aria.decal.decals option can be either an Object or an Array. If it is an Object, all data will have the same decal style. If it is an Array, each item in the array represents a decal style and data items will cycle through the array in order.
ARIA label generation algorithm flow
The accessibility description generation process follows these steps: First, check if aria.enabled is true and aria.label.enabled is true; if not, no description is generated. If aria.label.description is defined, use it as the full description. Otherwise, generate the description by using templates: if title.text exists, use aria.label.general.withTitle; otherwise use aria.label.general.withoutTitle. Then append series descriptions using aria.label.series templates, followed by data descriptions for each series using aria.label.data templates.
ARIA example with pie chart
Example code showing ARIA configuration with a pie chart: The option has aria.enabled set to true, a title with text 'User access sources for a site' centered, and a pie series with name 'access source' containing five data items with values and names. The generated aria-label attribute reads: "This is a chart of 'Source of user access to a site.' The chart type is a pie chart that indicates the source of the visit. The data is - direct access data is 335, mail marketing data is 310, union ad data is 234, video ad data is 135, search engine data is 1548."
Enable decal patterns with ARIA
To enable decal patterns, set aria.enabled to true and aria.decal.show to true in the option configuration. This will display applique textures as an additional visual aid to differentiate data beyond color alone.
ARIA support overview
Apache ECharts 4 complies with W3C WAI-ARIA (Accessible Rich Internet Applications Suite) specification by supporting automatic generation of intelligent descriptions based on chart configuration items. This allows blind people to understand chart content with the help of reading devices, making charts accessible to a wider audience.
ARIA enabled by default status
By default, ARIA is disabled. To enable it, set aria.enabled to true.
ARIA generates aria-label attribute
When ARIA is enabled, it automatically generates an aria-label attribute on the chart DOM element. The value of this label contains descriptions based on charts, series, data, and other configuration items.
ARIA description example for pie chart
For a pie chart with title 'Source of user access to a site' and data about direct access (335), mail marketing (310), union ad (234), video ad (135), and search engine (1548), the generated aria-label value is: 'This is a chart of "Source of user access to a site." The chart type is a pie chart that indicates the source of the visit. The data is - direct access data is 335, mail marketing data is 310, union ad data is 234, video ad data is 135, search engine data is 1548.'
ARIA default language configuration
The default language is defined by the language package (Chinese by default), but it can be configured with templates.
ARIA decal patterns for secondary color expression
Apache ECharts 5 supports applique textures as a secondary expression of color to further differentiate data. If aria.enabled is set to true and aria.decal.show is set to true, the default applique style will be adopted.
aria.label.description overall chart description
Use aria.label.description to specify the overall description of a chart. This is useful for charts where the default generated descriptions of data points are not sufficient to represent the overall information, such as scatter plots with hundreds or thousands of points.
ARIA description generation flow
If aria.label.show is set to true, an accessibility description is generated, otherwise not. If aria.label.description is defined, it is used as the full description of the chart. Otherwise, the description is generated according to template stitching using the default algorithm. Templates can be modified at a fine-grained level, or overridden completely with aria.description.
aria.label.general.withTitle template usage
When title.text is present, aria.label.general.withTitle template is used. When there is no title text, aria.label.general.withoutTitle is used. The aria.label.general.withTitle template supports a template variable '{title}', which will be replaced with the chart title. For example, if the template is set to 'The chart title is {title}.' and the chart title is 'Price Distribution', it will be interpreted to 'The chart title is Price Distribution.'
ARIA description generation sequence
After generating the title description, the description of the series (aria.label.series) and the description of the data for each series (aria.label.data) are generated in turn. Each template may include template variables to replace actual values.
aria.decal.decals custom decal pattern configuration
To customize the decal pattern beyond the default applique pattern, use aria.decal.decals to configure flexible decal patterns.
Aria component no longer imported by default in v5
The aria component is no longer imported by default in v5. If needed, import manually: import { AriaComponent } from 'echarts/components'; echarts.use(AriaComponent); Or require('echarts/lib/component/aria');
Accessibility theme colors and high-contrast themes
Apache ECharts 5 took accessibility into account when designing the new default theme. The brightness and color values of the colors were repeatedly tested to help accessibility users clearly identify the chart data. A special high-contrast theme is also provided for developers with further accessibility needs to differentiate data with higher contrast colors.
Decal patterns feature for accessibility and visual distinction
ECharts 5 provides a new feature of decals (patterns) to help users further differentiate data by using patterns to assist with color representation. Decal patterns can help distinguish data in printed materials like newspapers and books that have only single or few colors, and can use graphical elements to facilitate more intuitive understanding of data.