Accessibility features

External library: @elastic/charts v64.1.0

Elastic Charts provides some accessibilty features for all users.

Available a11y-related features

• Chart titles
• Chart descriptions
• Chart data in tabular form*
• Texture fill*
• Semantic groupings*

*Not all chart types that may benefit from this feature have it implemented as of yet

Titles

ariaLabel and ariaLabelledBy props can be set through the <Settings /> component.

ariaLabel takes a string label which will be visually hidden whereas theariaLabelledBy prop can tie the chart to other accessible elements elsewhere in your app.

<>
  <h1 id="randomHeadingId">Days of the week: weekdays vs weekends</h1>
  <Chart>
    <Settings
      ariaLabelledby="randomHeadingId"
    />
    <BarSeries {...props} />
  </Chart>
</>

If using ariaLabel, you can set a heading level for it by passing in ariaLabelHeadingLevel. h1 through h6 are valid options (p is the default).

You may want to set a heading level if there are multiple charts on the page but you want to draw attention to a select few or if a specific chart is the main content of the page.

<Chart>
  <Settings
    ariaLabel="Days of the week: weekdays vs weekends"
    ariaLabelHeadingLevel="h1"
  />
  <BarSeries {...props} />
</Chart>

Descriptions

ariaDescription and ariaDescribedBy props can be set through the <Settings /> component.ariaDescription takes a string description which will be visually hidden whereas ariaDescribedBy prop takes an id that you have rendered elsewhere in your app.

<Chart>
  <Settings
    ariaLabel="Days of the week: weekdays vs weekends"
    ariaDescription="Bar one is labelled weekdays and has a value of 5. Bar two is labelled weekends and has a value of 2."
  />
  <BarSeries {...props} />
</Chart>

warning

ariaDescribedBy will override ariaDescription if both are specified.

ariaUseDefaultSummary is a boolean defaulted to true. The default summary is bare bones and only reports the chart type(s). Some chart types provide more information but today that is only Gauge and Goal charts. If you are passing in a custom description, you can disable this prop.

<>
  <h1 id="randomHeadingId">Days of the week: weekdays vs weekends</h1>
  <p id="randomDescId">Bar chart with two bars. Bar one is labelled weekdays and has a value of 5. Bar two is labelled weekends and has a value of 2.</p>
  <Chart>
    <Settings
      ariaLabelledby="randomHeadingId"
      ariaDescribedBy="randomDescId"
      ariaUseDefaultSummary={false}
    />
    <BarSeries {...props} />
  </Chart>
</>

Tables

A visually hidden data table is rendered for some chart types. ariaTableCaption sets a custom caption on that table. Consider the table caption supplementary to the description. Use it to fill in any gaps that might be created when converting the chart to a tabular format.

note

In version 64.1.0, data tables are only available for partition charts.

Partition charts include: sunburst, treemap, icicle, flame, mosaic, and waffle.

Loading...

For the provided example, a visually hidden data table is rendered with the caption we passed on ariaTableCaption.

<p>There is a great variety of reported favorite fruit</p>

<dl>
  <dt>Chart type:</dt>
  <dd>sunburst chart</dd>
</dd>

<table>
  <caption>
    After Clementine (22), individual results are not labelled as the segments become too small
  </caption>
  <thead>
    <tr>
      <th scope="col">Label</th>
      <th scope="col">Value</th>
      <th scope="col">Percentage</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th>Apple</th>
      <td>100</td>
      <td>27%</td>
    </tr>
    {/* rows abbreviated */}
    <tr>
      <th>Durian</th>
      <td>1</td>
      <td>0%</td>
    </tr>
  </tbody>
</table>

Texture fill

You can set a texture fill for charts with TextureStyles interface.

note

In version 64.1.0, texture fills are only available for XY charts.

XY charts include: area, bar, and histogram.

Loading...

Semantic groupings

You can add meaning to your color segments by using the bandLabels prop.

note

In version 64.1.0, semantic groupings are only available for goal and gauge charts.

Loading...

For the provided example, visually hidden content is rendered with a goal description list generated from the bandLabels prop.

<p>Revenue 2020 YTD</p>
<p>(thousand USD</p>
<p>This goal chart has a target of 260.</p>
<dl>
  <dt>Chart type:</dt>
  <dd>horizontalBullet chart</dd>
  <dt>Minimum:</dt>
  <dd>0</dd>
  <dt>Maximum:</dt>
  <dd>300</dd>
  <dt>Target:</dt>
  <dd>260</dd>
  <dd>Value:</dd>
  <dt>280</dt>
</dl>
...
<dl class="echScreenReaderOnly echGoalDescription">
  <dt>0 - 100</dt>
  <dd>cold</dd>
  <dt>100 - 125</dt>
  <dd>brisk</dd>
  <dt>125 - 150</dt>
  <dd>warm</dd>
  <dt>150 - 250</dt>
  <dd>hot</dd>
</dl>