KPI Bar
KPI Bars display numerical or graphical indications of important business measurements. They provide at-a-glance status of specific business metrics and help drive business decisions.
Standard KPI Bar
When to Use
- To display the most important business metrics in a persistent manner.
- When metrics can be represented by 1-2 values and/or a simple graphical display.
When Not to Use
- Do not use if data is too complex to provide an immediate understanding of the metric.
Examples
- Standard KPI Bar (shown above)
- Condensed KPI Bar
- Tabbed KPI Bar
- Condensed Tabbed KPI Bar
Usage
- KPI Bars appear at the top of the screen, below the header.
- Each indicator includes up to three elements: label, primary value, secondary value or simple visualization. Common visualizations used in KPI Bars include spark line charts, half-circle gauges, and bullet gauges.
- If the metrics require more detail, use a set of Panels or carousel to present an overview. Follow Color Usage Guidelines to express positive and negative values and to communicate status. For example, success green and error red are used to convey how numbers change over time, while warning yellow is used to convey that a metric is off track.
- Prioritize the display of KPIs so that the most important are positioned toward the left. This will ensure that the most important indicators appear in the visible space when the screen size scales.
- A condensed header should be use on all pages with a KPI Bar.
- The KPI Bar may remain fixed at the top of the page.
Examples
The following examples contain code for both the standard and the condensed versions. Some HTML may be unused if using only a single version.
Tabbed KPI Bar
Use KPI tabs when the content of the page updates based on a selected KPI.
Condensed KPI Bar
The condensed version is recommended when there is only 1-2 values in each KPI.
Condensed Tabbed KPI Bar
The tabbed condensed version is recommended when there is only 1-2 values in each KPI and when selecting a KPI updates the page to show supporting data specific to that indicator.
Responsive Behavior of KPI Bar
Let the target screen size of most users guide the number of indicators included in the bar (6-8 works well for large displays). As screen width decreases, arrows appear on the left or right to allow navigation to the overflow indicators.
There are several options for condensing a KPI Bar in the context of small and x-small screens:
- Standard Scroll - Recommended when the user is likely to want to see KPI in the same context as the supporting data.
- Carousel - Recommended for non-tabbed KPI Bars and when it is less critical to see KPIs alongside supporting data (for example, for users who only want to view the high-level data).
- Stacked Navigation - Recommended for tab KPI Bars
Condense on Scroll
When using the KPI and taking advantage of the Fixed Panel capability, the KPI will automatically transition to a condensed state.
Developer Notes
Standard KPI Bar
This example contains the standard KPI Bar. This example demonstrates the Fixed Panel abilities to lock to the top of the view port and condense on scroll. This example will also change into a stack layout when displayed on xs screen sizes.
Tabbed KPI Bar
This example demonstrates the ability of the KPI to function as tabs. This example also demonstrates the Fixed Panel abilities to lock to the top of the view port and condense on scroll.
Accessibility Notes
Because tabs are not native HTML elements, it is important to use appropriate markup to ensure that the tabs are accessible to screen-readers and other assistive devices. This is generally accomplished by using ARIA attributes for semantic enhancements. Javascript is then used to dynamically manage various attributes that are used to inform assistive devices of the current state of the tabs. The ARIA roles and attributes required to make the tabs component fully accessible are described below.
Carousel controls when using tabs are not accessible by keyboard, as tabbing through the KPI will automatically advance the KPI’s in the carousel and would not provide any additional functionality.
KPI Tab Navigation Controls
The spark-kpi--tabs element requires a role of menubar, which is typically used to denote menus that are visible and presented horizontally.
The spark-kpi__list element contains the actual list of tabs used for navigation and requires a role of tablist to indicate to screen-readers and assistive devices that its child elements are selectable tabs. The spark-kpi__item list items have a role of presentation as they do not have any functional or interactive importance but are semantically required to build a valid HTML list. This is explained further below.
As mentioned in the Developer Notes, the current tab will have aria-selected="true" applied to the list item, and there can only be one selected tab at a time. You will need to set the aria-selected="true" on the first selected tab.
Within each spark-kpi__item list item is an anchor tag, <a>, that contains the label of the tab. This element has an href attribute defined to make the element keyboard accessible. If an href is not provided, make sure a tabindex="0" is provided as a fallback to make sure it is keyboard-focusable. A role of tab is then set to to this element to indicate that it is the mechanism for selecting tab content. The reason this element has role="tab" instead of its parent <li> is that the tab needs to be focusable directly, whereas the <li> element is not a focusable element. The aria-controls attribute is provided to indicate which tab panel the specific anchor controls. The value of this attribute is the id of the associated tab panel. This attribute will be controlled dynamically with javascript.
Each tag should contain a spark-assistive-text element to provide text to screen-readers and assistive technologies as the individual elements within the KPI are hidden to these technologies. It is recommended to use plain language for this text
Tab Content Panels
The spark-tabs__panel containers hold the tab contents and should be uniquely identified with an id attribute. The value of this id is then used as the value of the aria-controls attribute for the tab that controls the specific tab panel. A role of tabpanel identifies the container as an individual tab panel to screen-readers and assistive devices. If a tab is initially hidden, an aria-hidden attribute should be provided and set to true, otherwise it should be set to false if you intend for this tab to be the initial visible tab. Javascript will be used to manage the aria-hidden state when a user interacts with different tabs, but this attribute and value should always be initially set to the desired value.
Standard KPI Carousel Controls
When using a non-tabbed KPI Bar, the carousel controls have an aria-label attached to them. This provides context for which direction the KPI Bar will advance. the text of these buttons can be modified with the nextLabel and previousLabel configuration options.
Standard KPI Assistive Context
Like in the KPI tabbed example, each KPI item should contain an spark-assistive-text to help clarify the KPI’s meaning. With it’s various icons and colors, a plan language description is recommended.