sp-meter

NPM 1.7.0

View Storybook

Try it on Stackblitz
Overview API Changelog

Overview

An <sp-meter> is a visual representation of a quantity or achievement. The meter's progress is determined by user actions, rather than system actions.

Usage

See it on NPM! How big is this package in your project? Try it on Stackblitz

yarn add @spectrum-web-components/meter

Import the side-effectful registration of <sp-meter> via:

import '@spectrum-web-components/meter/sp-meter.js';

When looking to leverage the Meter base class as a type and/or for extension purposes, do so via:

import { Meter } from '@spectrum-web-components/meter';

Anatomy

The meter consists of several key parts:

  • A label that describes what is being measured
  • A progress track showing the total possible range
  • A fill bar indicating the current progress
  • A percentage value showing the numeric progress
<sp-meter progress="71">Tasks Completed</sp-meter>

Label

The label is the text that describes what is being measured. It can be provided either through the default slot or the label attribute.

<sp-meter progress="15">Course Progress</sp-meter>
<br />
<sp-meter progress="15" label="Course Progress"></sp-meter>

Options

Sizes

Small Medium 
<sp-meter size="m" progress="25">Tasks Completed</sp-meter>
 Large Extra Large

Variants

The meter supports several variants to convey different semantic meanings:

Informative

By default, the informative variant can be used to represent a neutral or non-semantic value, such as the number of tutorials completed.

<sp-meter progress="50">Storage Space</sp-meter>
 Positive Notice Negative

Label Position

A meter can be delivered with its labeling displayed above its visual indicator or to either side. Use the boolean side-label attribute to define where this content should appear.

<sp-meter side-label progress="68">Side Label</sp-meter>

Accessibility

The <sp-meter> element is rendered with role="meter progressbar" to ensure proper semantics for assistive technologies. The current progress value is set as a percentager via the progress attribute and is exposed to assistive technology via aria-valuenow.

<sp-meter progress="71" label="Download Progress">Download Progress</sp-meter>

Include a label

A meter is required to have either a visible text label or a label attribute.

Don't override color

The meter's variants provide semantic meaning through both color and ARIA attributes, ensuring that information is not conveyed through color alone. The progress track and fill maintain sufficient contrast for visibility.