Components / Library version 3.26.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. Hybrid charts have been replaced by the Progress Monitor 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.

Properties Examples Events Accessibility Notes

* 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-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.

Deprecated properties of wm-chart

completion-message
string
The text to display when the amount represents 100% in charts of the deprecated hybrid type
show-values
percentage | amount | none
Previously, display format for the individual values (where applicable). Defaults to none. Deprecated in favor of value-format.

Deprecated properties of wm-chart-slice

onclick
function
Previously, use the native onclick property to attach a function to the click event. Deprecated in favor of using popover-button-text and listening to the wmChartPopoverButtonTriggered event.

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).

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.

In a compound component like Select or Action Menu, child components are rendered in the parent's slot element, part of its shadow DOM tree. Slots essentially serve as a placeholder for markup that you the developer define in the light DOM tree, like <wm-menuitem>, <wm-option>, text content, or other child elements.

The browser distributes the child elements defined in the light DOM into the shadow DOM of the parent. The result is a flattened DOM tree—a merger of the the light DOM and the shadow DOM. This flattened tree is what you see in DevTools and what is rendered on the page.

With the standard implementation of the component, dynamically updating the child items will throw an error. Elm's efficient diffing of the DOM will register that only the child items have changed and try to update them, but the component has already been composed.

Rendering the component in a Keyed node and giving it a dynamic id will cause the entire component, rather than just the child items, to render anew, avoiding the error.