D3 chart
What component has
Default attributes
The following table describes roles and attributes the component already has.
Component | Attribute | Usage |
---|---|---|
Chart.* | role="group" | Presents the chart plot and its legend as a single group. |
ChartLegend | role="group" | Presents the legend items as a single group. |
aria-label="Chart legend" | Defines an accessible name for the chart legend. Set by default only if using Chart.* . If you're adding the legend manually, you have to set the accessible name for it. |
Accessible data summary
All charts created with the @semcore/d3-chart
package are accessible for screen readers, such as JAWS, NVDA, Apple VoiceOver, Chrome Vox and others. With keyboard or braille display navigation users may reach a block that's hidden by default. That block contains anchor links for faster navigation, an autogenerated summary of the chart, and a plain table containing all the data used for visualization.
The data table may not look pretty but it's fully accessible for screen readers.
TIP
Refer to accessible summaries examples to learn how different summaries look.
Data summarizer architecture
Data summarization is performed on the client side in linear time, linear memory and split into three phases:
- Catching data structure hints from visualization components, such as
<Line />
or<Bar />
. - Extracting data insights into abstract insights blocks.
- Transforming the abstract insights blocks into human-readable text.
Considerations for developers
Recommended attributes
Component | Attribute | Usage |
---|---|---|
Chart.* | aria-label or aria-labelledby | Required when using Chart.* . Defines an accessible name for the group with the chart plot and the legend. |
Plot | locale | Defines the language of the chart. Set it to generate the data summary correctly. |
patterns | Enables pattern fills and dashed lines instead of solid fills and lines, and symbols instead of dots. Read more about patterns. | |
ChartLegend | aria-label or aria-labelledby | Required when using ChartLegend explicitly. Defines an accessible name for the chart legend. |
patterns | Only with shape="checkbox" . Shows pattern symbols in addition to checkboxes in legend items. |
How to ensure correct summary generation
- Check that the generated summary describes your chart correctly. Press Tab to open the summary and review the text and the table.
- Add both the
XAxis.Title
and theYAxis.Title
components. These components help the summarizer generate a better chart summary. - Make sure that all the information displayed in the tooltip is also provided in the
data
property of<Plot />
. - Update the accessible summary when the user checks or unchecks legend items.
- If you are redefining children rendering of the
XAxis.Ticks
orYAxis.Ticks
component, return both thechildren
and thevalue
properties. - If your chart is highly customized, the summarizer may struggle with the summary. To fix that, either tweak the data summarizer configuration or add your own summary manually.
Redefining children rendering of ticks
If you are redefining children rendering of <XAxis.Ticks>
or <YAxis.Ticks>
, beside children
return the value
property in the render function. This way value
will be used to describe a tick in the generated summary. Note that render function may be called more times than ticks displayed because some ticks making sense for summary generation may make no sense for visualization.
<XAxis>
<XAxis.Title>Year</XAxis.Title>
<XAxis.Ticks ticks={xScale.ticks(6)}>
{({ value }) => ({
value: new Date(value),
children: formatDate(value),
})}
</XAxis.Ticks>
</XAxis>
Tweak data summarizer configuration
Sometimes the chart summary looks similar to what you expect, but not good enough. For example, your data is too variable and the summarizer seems to be too sensitive. In this case you can tweak the summarizer configuration.
PlotSummarizerConfig
Name | Type | Description |
---|---|---|
disable | boolean | Totally disable automatic data summarization |
override | string | Disable automatic data summarization and use provided text |
trendTangens | {static?: number; weak?: number; medium?: number; strong?: number } | Tuning up time series trends analyzing. Represents angle tangens of time series change of different strength |
movingAverage | {longSize?: number; shortSize?: number; notableDiff?: number } | Tuning up time series local trends detection based on moving averages |
dataType | "time-series" | "points-cloud" | "values-set" | The way data to be interpreted as. By default is based on used used Plot elements and data structure. |
clustersGridSize | number | Grid size to split data of point clouds into clusters. |
maxListSymbols | number | Limits some output lists in chart alt text |
datesWithTime | boolean | Always add time to dates in chart alt text * |
clustersLimit | number | Described clusters count before text "and X more" |
valuesLimit | number | Described values count before text "and X more" |
groupsLimit | number | Described grouped value groups count before text "and X more" |
additionalFields | string[] | Additional field for extra text description to the data * |
titlesFormatter | (key: string | number | null) => string | undefined | Allows to format titles (e.g. axes) in alt text and data table |
valuesFormatter | (value: unknown, key: string | number | null) => string | undefined | Allows to format values in alt text and data table |
Add summary manually
If the automatically generated summary isn’t suitable for the provided data, disable the summarizer whatsoever and provide your own text.
<Plot
scale={[xScale, yScale]}
width={width}
height={height}
data={data}
a11yAltTextConfig={{
override:
"This chart represents the sales of our great unicorn startup. We haven't sold anything.",
}}
/>
Pattern fills, dots and lines
Using patterns in charts instead of just colors makes them easier to understand for people who are colorblind or have low vision. Some colors can be hard to differentiate for these users, even if selected thoughtfully and with different contrasts. This can make it hard to read charts. Adding patterns helps more people see the differences between data sets clearly.
The pattern
property enables pattern fills in charts with filled areas, symbols instead of dots, and dashed lines instead of solid ones in charts without filled areas.
TIP
Refer to our live examples for more details on the feature usage.
Contributing to accessible summary module
If you're interested in expanding the chart accessible data summary module, or ejecting the module into a separated package, feel free to open a pull request.