@m3e/progress-indicator

The m3e-linear-progress-indicator and m3e-circular-progress-indicator components provide accessible, animated progress indicators for tracking the completion of tasks or processes. Both components support multiple modes and are fully customizable via CSS custom properties.

This package is part of M3E monorepo, a unified suite of Material 3 web components. Explore the docs to see them in action.

📦 Installation

npm install @m3e/progress-indicator

💻 Editor Integration

This package includes a Custom Elements Manifest to support enhanced editor tooling and developer experience.

Visual Studio Code

To enable autocomplete and hover documentation for @m3e/progress-indicator, install the Custom Elements Manifest Language Server extension. It will automatically detect the manifest bundled with this package and surface tag names, attributes, slots, and events in supported files.

Alternately, you can explicitly reference the html-custom-data.json and css-custom-data.json in your workspace settings:

{
  "html.customData": ["./node_modules/@m3e/progress-indicator/dist/html-custom-data.json"],
  "css.customData": ["./node_modules/@m3e/progress-indicator/dist/css-custom-data.json"]
}

🚀 Native Module Support

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/[email protected]/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js"
    }
  }
</script>

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

🗂️ Elements

• m3e-linear-progress-indicator — A horizontal bar for indicating progress and activity.
• m3e-circular-progress-indicator — A circular indicator of progress and activity.

🧪 Example

The following example illustrates determinate progress indicators.

<m3e-linear-progress-indicator value="30"></m3e-linear-progress-indicator>
<m3e-circular-progress-indicator value="30"></m3e-circular-progress-indicator>

The next example illustrates indeterminate progress indicators.

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

📖 API Reference

🗂️ m3e-linear-progress-indicator

This section details the attributes and CSS custom properties available for the m3e-linear-progress-indicator component.

⚙️ Attributes

| Attribute | Type | Default | Description | | ------------ | --------------------------------------------------------- | --------------- | -------------------------------------------------------------------- | | buffer-value | number | 0 | A fractional value, between 0 and max, indicating buffer progress. | | max | number | 100 | The maximum progress value. | | mode | "determinate" \| "indeterminate" \| "buffer" \| "query" | "determinate" | The mode of the progress bar. | | value | number | 0 | A fractional value, between 0 and max, indicating progress. |

🎛️ CSS Custom Properties

| Property | Description | | --------------------------------------------------------------- | ----------------------------------------------------- | | --m3e-linear-progress-indicator-thickness | Thickness (height) of the progress bar. | | --m3e-linear-progress-indicator-shape | Border radius of the progress bar. | | --m3e-progress-indicator-track-color | Track color of the progress bar (background/buffer). | | --m3e-progress-indicator-color | Color of the progress indicator (foreground). | | --m3e-linear-wavy-progress-indicator-amplitude | Amplitude of the wavy variant. | | --m3e-linear-wavy-progress-indicator-wavelength | Wavelength of the wavy variant. | | --m3e-linear-wavy-indeterminate-progress-indicator-wavelength | Wavelength of the indeterminate/query wavy variant. |

🗂️ m3e-circular-progress-indicator

This section details the attributes, slots, and CSS custom properties available for the m3e-circular-progress-indicator component.

⚙️ Attributes

| Attribute | Type | Default | Description | | ------------- | --------- | ------- | ------------------------------------------------------------------ | | indeterminate | boolean | false | Whether to show something is happening without conveying progress. | | max | number | 100 | The maximum progress value. | | value | number | 0 | A fractional value, between 0 and max, indicating progress. |

🧩 Slots

| Slot | Description | | ----------- | -------------------------------------------------- | | (default) | Renders the content inside the progress indicator. |

🎛️ CSS Custom Properties

| Property | Description | | --------------------------------------------------- | --------------------------------------------------- | | --m3e-circular-flat-progress-indicator-diameter | Diameter of the flat variant. | | --m3e-circular-wavy-progress-indicator-diameter | Diameter of the wavy variant. | | --m3e-circular-wavy-progress-indicator-amplitude | Amplitude of the wavy variant. | | --m3e-circular-wavy-progress-indicator-wavelength | Wavelength of the wavy variant. | | --m3e-circular-progress-indicator-thickness | Thickness of the progress indicator. | | --m3e-progress-indicator-track-color | Track color of the progress indicator (background). | | --m3e-progress-indicator-color | Color of the progress indicator (foreground). |

🤝 Contributing

See the root monorepo CONTRIBUTING.md for guidelines on contributing to this package.

📄 License

This package is licensed under the MIT License.