Components / Library Version 4.9.0

Chart

The chart component renders a doughnut or bar chart, including the popover. It is composed of a parent element wm-chart and children elements wm-chart-slice.

The component type determines the number of slices and you must provide all of them (see the notes tab).

The popover will render if both props popover-title and popover-text are provided.

There are three types of doughnut charts and five types of bar charts. Each chart type was created to handle specific design needs. Below is a guide for appropriate usage of each type. For charts that show change in data over time, see the Line Chart component.

Chart Type Usage
Doughnut1 This chart displays two states within a category and an unknown state, for example Direct, Indirect and Unspecified. Slices are sorted in descending order.
Doughnut2 Similar to Doughnut1, this chart displays four states within a category. In this variant two states have a positive and negative connotation, a third (optional) one is neutral, and the last is unknown/unset. An example of this would be Met, Not Met, Conditionally Met, Not Started. Slices are sorted in descending order.
Doughnut3 This chart should be used for multiple comparisons. Slices are sorted in descending order.
Bar2 This chart displays three or four qualitative states within a category and an unknown state. For example: Met, Not Met, Conditionally Met, Awaiting Review, Not Submitted.
Bar3 This chart compares four qualitative states within a category, two positive and two negative. For example, Met, Exceeded, Approached, and Not Met.
Bar4 This chart displays the progress status for a category. For example Not Started, In Progress, and Complete.
Bar5 This chart should be used to compare up to seven qualitative states for a category.
Bar6 This simple bar chart should be used to compare discrete categorical data.
Bar7 This simple bar chart compares discrete categorical data with intentional color associations for their respective labels.

See the different types in the examples tab.

PropertiesExamplesAPIAccessibilityNotes

* Required property

Properties of the parent element wm-chart

label *
string
A description for the chart. Only certain types display it, but it is required in all cases, for accessibility reasons.
label-position
"top" | "none"
For bar type charts. Defaults to top. If set to none no label is displayed, but an external label matching the chart's label should be visually grouped with the chart.
label-width
string: CSS width value
For types bar6 and bar7 only — determines bar label width. Defaults to 150px.
chart-type
doughnut1 | doughnut2 | doughnut3 | bar1 | bar2 | bar3 | bar4 | bar5 | bar6 | bar7
The type of chart to display. Defaults to doughnut1.
not-started-color
boolean
For type bar5 only — adds a gray color for the first slice (useful when the first slice corresponds to "not started" elements).
show-grid
boolean
For type bar6 only — show or hide the grid. Defaults to true.
show-legend
boolean
Show or hide the legend. This is useful in particular if several charts share the same legend (you can hide it on every chart but the first one). The legend is still read by screen readers, and for that reason the legend property on the wm-chart-slice elements is still required.
show-bar-legend
boolean
For type bar7 only — show or hide the y-axis bar legend. Defaults to false.
subinfo
string
Optional text to display under the label. Doesn't display if the label is hidden.
value-format
percentage | amount | none
Display format for the individual values (where applicable). Defaults to none.

Properties of the children elements wm-chart-slice

amount *
string
Numeric value (whole number)
legend
string
Text for the legend. It can be omitted if a particular option has been removed, see Notes tab.
popover-title
string
The popover title. Titles with a negative value (starting with string "-") are colored red, while those with a positive value (starting with "+") are colored green. Any other string will have the default color (black).
popover-text
string
The popover text
popover-button-text
string
The text inside the popover button. If not provided, the button is not rendered.

Usage in HTML

Edit the code below to see changes reflected in the example above.

Javascript Sample

Example code for functionality.

Usage in Elm

Code generated from HTML.
wmChartPopoverButtonTriggered
Emitted by wm-chart when one of its popover buttons has been triggered. The event's detail property contains the wm-chart-slice element that has been triggered. See javascript sample in the examples tab for usage.

Screen Reader

Screen readers announce the following when the user tabs on a chart: "Interactive chart. Use arrow keys to browse elements, press Tab to exit."

Keyboard Support

Key Function
Arrow Down Arrow Right
  • If the chart is in focus, brings focus to the first segment and opens the popover.
  • If a segment is in focus, brings focus to the next segment.
Arrow Up Arrow Left
  • If the chart is in focus, brings focus to the last segment and opens the popover.
  • If a segment is in focus, brings focus to the previous segment.
Tab Exits the chart (bringing focus to the next focusable element).
Shift + Tab Exits the chart (bringing focus to the previous focusable element).
Enter Triggers the popover button (if popover is open and has a button).

Small chart slices that have values greater than 0 are given minimum widths for improved readability. Bar slices have a minimum width of 5px, and doughnut slices have a minimum width of 7 degrees.

When printed charts show slice values appended to their corresponding legend keys, as this information is typically acquired through keyboard interaction. Any text references to keyboard interaction are hidden. This behavior can be forced via the print-mode property.

Chart types bar 6 and bar 7 can handle instances where values are 0. For all other charts, devs should handle the empty state.

You must provide a <wm-chart-slice> for every option, even if they should not be displayed. This ensures that the component knows which option the slice corresponds to, and assigns the proper color to each slice.

There are two cases in which a slice should be hidden:

  1. When the option exists but its amount is "0"

    In this case, the legend should still include the option not represented in the graph. The <wm-chart-slice> should have an amount of "0" and an appropriate text for the legend.

  2. When the option has been removed (e.g. by the user)

    In this case, both the slice and its corresponding legend should be hidden. The <wm-chart-slice> should have an amount of "0" and no legend text. You may omit the attribute or pass it an empty string.