Components / Library version 3.20.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 compares two states within a category with the option to include an unknown state, for example Direct, Indirect and Unspecified. Slices are sorted in descending order.
Doughnut2 Similar to Doughnut1, this chart compares two states within a category, however, each has a positive and negative connotation. There is also an option for no specification. An example of this would be Met, Not 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 compares three qualitative states within a category, with an option for no answer such as Not Started, In Progress, Met, Not Met.
Bar3 This chart compares four qualitative states within a category, two positive and two negative, without an option for no answer, such as Met, Exceeded, Approached, Not Met.
Bar4 This chart displays the progress status for a category, for example Not Started, In Progress, Complete.
Bar5 This chart should be used for multiple comparisons.

See the different types in the examples tab.

Properties Examples Events Accessibility Notes

* Required property

Properties of the parent element wm-chart

chart-type
doughnut1 | doughnut2 | doughnut3 | bar1 | bar2 | bar3 | bar4 | bar5
The type of chart to display. Defaults to doughnut1.
label *
string
A description for the chart. Only certain types display it, but it is required in all cases, for accessibility reasons.
subinfo
string
Optional text to display under the label. Doesn't display if the label is hidden.
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.
not-started-color
boolean
Adds a gray color for the first slice (useful when the first slice corresponds to "not started" elements). Only for type "bar 5".
value-format
percentage | amount | none
Display format for the individual values (where applicable). Defaults to none.

Properties of the children elements wm-chart-slice

legend
string
Text for the legend. It can be omitted if a particular option has been removed, see Notes tab.
amount *
string
Numeric value (whole number)
popover-title
string
The popover title
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.