The m3e-loading-indicator component shows indeterminate progress for a short wait time. It uses animation to grab attention, mitigate perceived latency, and indicate that an activity is in progress.

import "@m3e/web/loading-indicator";

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

There are two loading indicator appearance variants: uncontained (default) and contained. Use the variant attribute to change the appearance.

<m3e-loading-indicator></m3e-loading-indicator>
<m3e-loading-indicator variant="contained"></m3e-loading-indicator>

Material 3's pull-to-refresh pattern uses the loading indicator as part of the gesture, letting it rotate in reverse based on how far the user has dragged before the refresh begins.

Use the pull-progress attribute (or pullProgress property) to control the indicator's pull-to-refresh progress. A value of 1 represents one full turn of rotation. Changing the value updates the indicator's counterclockwise rotation, and holding the value steady leaves it still. To return to the normal clockwise animation, remove the attribute or set the property to null.

The following example illustrates use of the m3e-pan-gesture to capture drag movement and maps 120px of downward drag to a full rotation cycle. See Gestures for more information.

<div id="pull-target">
  <m3e-loading-indicator id="indicator" variant="contained"></m3e-loading-indicator>
</div>
<m3e-pan-gesture id="pull-gesture" for="pull-target" lock-axis="y"></m3e-pan-gesture>

<script>
  const target = document.getElementById("pull-target");
  const indicator = document.getElementById("indicator");
  const gesture = document.getElementById("pull-gesture");
  const pullDistancePerTurn = 120;

  gesture.addEventListener("gesture", ({ detail }) => {
    switch (detail.phase) {
      case "start":
        indicator.pullProgress = 0;
        break;
      case "update":
        indicator.pullProgress = Math.max(0, detail.totalDeltaY / pullDistancePerTurn);
        break;
      case "cancel":
      case "end":
        indicator.pullProgress = null;
        break;
    }
  });
</script>

The m3e-loading-indicator implements the ARIA role="progressbar" pattern. By default, the component sets aria-valuemin to 0 and aria-valuemax to 100.

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

The @m3e/web 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/web/dist/loading-indicator.js"></script>

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

<script type="importmap">
  {
    "imports": {
      "tslib": "https://cdn.jsdelivr.net/npm/tslib@2.8.1/+esm",
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "lit/": "https://cdn.jsdelivr.net/npm/lit@3.3.0/",
      "lit-html": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/+esm",
      "lit-html/directive.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directive.js",
      "lit-html/directives/if-defined.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directives/if-defined.js",
      "lit-html/directives/class-map.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directives/class-map.js",
      "@lit/reactive-element": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/+esm",
      "@lit/reactive-element/": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/",
      "@m3e/web/core": "/node_modules/@m3e/web/dist/core.js"
    }
  }
</script>

For production builds, use the minified files to ensure optimal load performance.

The @m3e/web 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.