The m3e-linear-progress-indicator and m3e-circular-progress-indicator components provide accessible, animated progress indicators for tracking the completion of tasks or processes.

npm i @m3e/progress-indicator

This section outlines usage examples and configuration guidance for the components in this package.

Use the m3e-circular-progress-indicator to present a circular indicator of progress and activity. This component supports two modes (determinate and indeterminate) and two appearance variants (flat and wavy). Use the variant attribute to change the appearance.

By default, circular progress indicators are determinate. Use the value attribute to indicate completion percentage and use max to specify the total number of steps or units of progress. In addition, you can provide content in the default slot.

<m3e-circular-progress-indicator value="25">25</m3e-circular-progress-indicator>
<m3e-circular-progress-indicator variant="wavy" value="25">25</m3e-circular-progress-indicator>

Use the indeterminate attribute to change the mode to indeterminate. In this mode, value and max are ignored.

<m3e-circular-progress-indicator indeterminate></m3e-circular-progress-indicator>
<m3e-circular-progress-indicator variant="wavy" indeterminate></m3e-circular-progress-indicator>

Use the m3e-linear-progress-indicator to present a horizontal bar for indicating progress and activity. This component supports four modes: determinate (default), indeterminate, buffer, and query.

Use the mode attribute to change the mode. As with a circular indicator, use variant to set the appearance to either flat (default) or wavy.

Use the determinate mode where the percentage of the operation complete is known. Use the value attribute to indicate completion percentage and use max to specify the total number of steps or units of progress. This is the default mode.

When using the wavy variant, the indicator transitions to the flat appearance automatically when progress reaches 100%.

<m3e-linear-progress-indicator value="25"></m3e-linear-progress-indicator>
<m3e-linear-progress-indicator variant="wavy" value="25"></m3e-linear-progress-indicator>

Use the indeterminate mode to express that something is happening, but without conveying discrete progress. In this mode, value and max are ignored.

<m3e-linear-progress-indicator mode="indeterminate"></m3e-linear-progress-indicator>
<m3e-linear-progress-indicator variant="wavy" mode="indeterminate"></m3e-linear-progress-indicator>

Use the buffer mode to indicate some activity or loading from the server. In this mode, value determines the progress of the primary bar while the buffer-value attribute is used to show buffering progress.

As with determinate mode, when using the wavy variant, the indicator transitions to the flat appearance automatically when progress reaches 100%.

<m3e-linear-progress-indicator mode="buffer" value="10" buffer-value="25"></m3e-linear-progress-indicator>
<m3e-linear-progress-indicator variant="wavy" mode="buffer" value="10" buffer-value="25"></m3e-linear-progress-indicator>

Use the query mode to indicate pre-loading before the actual loading starts. In this mode, value and max are ignored.

<m3e-linear-progress-indicator mode="query"></m3e-linear-progress-indicator>
<m3e-linear-progress-indicator variant="wavy" mode="query"></m3e-linear-progress-indicator>

Progress indicators implement the ARIA role="progressbar" pattern. They set aria-valuemin to 0, aria-valuenow to value, and aria-valuemax to max.

Always provide an accessible label via aria-label or aria-labelledby for each progress indicator.

This package uses JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following.

<script type="module" src="/node_modules/@m3e/progress-indicator/dist/index.js"></script>

In addition, you must use an import map to include dependencies.

<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js"
    }
  }
</script>

For production, use index.min.js for faster load times.

This package includes a Custom Elements Manifest (custom-elements.json), which documents the properties, attributes, slots, events and CSS custom properties of each component.

You can explore the API below, or integrate the manifest into your own tooling.