Accessibility features

---

@elastic/charts v68.0.2

Elastic Charts provides some accessibility 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.

✄𐘗
tsx code block:
✄𐘗<>
  <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.

✄𐘗
tsx code block:
✄𐘗<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.

✄𐘗
tsx code block:
✄𐘗<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>

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.

✄𐘗
tsx code block:
✄𐘗<>
  <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.

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.

✄𐘗
tsx code block:
✄𐘗<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.

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.

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.

✄𐘗
tsx code block:
✄𐘗<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>