Progress Indicator

Progress indicators show the real-time status of a process. Features include determinate and indeterminate modes, circular indicators, and expressive wavy linear bars.

Introduction

The MD3 Expressive Progress Indicator provides visual feedback for tasks that take more than a few seconds. It supports both Linear and Circular formats, and offers a unique Wavy design style that adds a layer of sophisticated motion to the standard progress bar. It handles both determinate (known progress) and indeterminate (unknown duration) states gracefully.

Anatomy

• Track: The background line or circle representing the total progress.
• Indicator: The active part of the bar or circle representing completed progress.
• Wavy Element (Optional): A dynamic SVG path that adds a wave effect to the indicator.

Variants

Linear Progress

Horizontal bars that are ideal for placement at the top of a surface or container.

Circular Progress

Circular indicators that are best for smaller spaces or when a more centered focus is required.

Features

Determinate vs Indeterminate

• Determinate: Use when the percentage of completion is known.
• Indeterminate: Use when the duration of the task is unknown.

Wavy Motion

The shape="wavy" prop transforms the flat progress bar into an animated wave. This expressive style is perfect for high-end interfaces that want to stand out.

Use Cases & Integration

Practical examples of progress indicators integrated into action controls like buttons during async operations.

Usage

Basic Linear Progress

import { ProgressIndicator } from "@bug-on/m3-expressive";

<ProgressIndicator value={60} aria-label="Loading profile status" />

Indeterminate Circular Progress

<ProgressIndicator variant="circular" aria-label="Loading resources" />

Expressive Wavy Progress

<ProgressIndicator 
  shape="wavy" 
  value={45} 
  amplitude={6} 
  wavelength={30} 
  aria-label="Processing video export"
/>

Best Practices

Do

• Use Determinate progress whenever the duration can be calculated.
• Provide an aria-label that describes what is being loaded.
• Use Linear progress for long processes like file uploads or page loads.
• Use Circular progress for smaller, contextual loading (e.g., inside a card).

Don't

• Don't use a progress indicator if the task takes less than 1 second.
• Don't switch between determinate and indeterminate states frequently; it can be confusing.
• Avoid using too many wavy indicators on a single page, as the motion can be distracting.

Accessibility

• Roles: Automatically applies role="progressbar".
• States: Manages aria-valuenow, aria-valuemin, and aria-valuemax for determinate states.
• Indeterminate: Removes aria-valuenow to signal unknown progress to screen readers.

API Reference

ProgressIndicator

Component ProgressIndicator nhận các thuộc tính chung cùng các cấu hình đặc trưng tùy theo kiểu hiển thị linear hoặc circular.

Shared Props (Thuộc tính dùng chung)

Linear-specific Props (Chỉ áp dụng khi variant="linear")

Circular-specific Props (Chỉ áp dụng khi variant="circular")