M3E Loading

A Flutter package providing Material 3 Expressive loading indicators with smooth morphing shape animations.

Features

• 🎨 Material 3 Expressive Design - Follows Google's latest design system
• ⚡ Smooth Animations - Spring-based morphing between 7 different shapes
• 📐 Flexible Sizing - Predefined constants or custom dimensions via double values
• 🎨 Background Support - Optional circular background color
• 🎯 Themeable - Respects ProgressIndicatorTheme or accepts custom colors
• ♿ Accessible - Semantic labels and respects disableAnimations
• 🚀 Zero Config - Works out of the box with Material theme

Installation

Add to your pubspec.yaml:

dependencies:
m3e_loading:
git:
url: https://github.com/dthuy62/m3e_loading.gitref: main

Or run:

flutter pub add m3e_loading --git-url=https://github.com/dthuy62/m3e_loading.git

Usage

Basic Usage

import'package:m3e_loading/m3e_loading.dart';
// Default size (40px)M3ELoadingIndicator()
// With predefined size constantM3ELoadingIndicator(size:M3ELoadingIndicator.sizeMD)

Flexible Sizing

Choose from predefined sizes or specify custom dimensions:

// Default size (40px)M3ELoadingIndicator()
// Predefined constants (recommended for consistency)M3ELoadingIndicator(size:M3ELoadingIndicator.sizeXS) // 28pxM3ELoadingIndicator(size:M3ELoadingIndicator.sizeSM) // 32pxM3ELoadingIndicator(size:M3ELoadingIndicator.sizeMD) // 40pxM3ELoadingIndicator(size:M3ELoadingIndicator.sizeLG) // 48pxM3ELoadingIndicator(size:M3ELoadingIndicator.sizeXL) // 56px// Custom size for special casesM3ELoadingIndicator(size:35.0)
M3ELoadingIndicator(size:100.0)

Custom Color

M3ELoadingIndicator(
size:M3ELoadingIndicator.sizeMD,
color:Colors.blue,
)

Background Color

Add a circular background behind the indicator:

// Solid backgroundM3ELoadingIndicator(
backgroundColor:Colors.grey.shade200,
)
// Semi-transparent background (useful for overlays)M3ELoadingIndicator(
backgroundColor:Colors.black.withOpacity(0.1),
)
// Combined with custom sizeM3ELoadingIndicator(
size:M3ELoadingIndicator.sizeLG,
backgroundColor:Theme.of(context).colorScheme.surfaceContainerHighest,
)

Using ProgressIndicatorTheme

ProgressIndicatorTheme(
data:ProgressIndicatorThemeData(
color:Theme.of(context).colorScheme.secondary,
),
child:M3ELoadingIndicator(),
)

Centered in Screen

Center(
child:M3ELoadingIndicator(),
)

Shape Morphing Sequence

The indicator morphs through 7 Material shapes in sequence:

1. Soft Burst
2. Cookie (9-sided)
3. Pentagon
4. Pill
5. Sunny
6. Cookie (4-sided)
7. Oval

Then loops back to Soft Burst.

API Reference

M3ELoadingIndicator

Main widget displaying the animated loading indicator.

Properties:

• size (double?) - Size of the indicator in logical pixels. Default: 40.0 (sizeMD constant)
• color (Color?) - Optional color override. If null, uses ProgressIndicatorTheme.color or ColorScheme.primary
• backgroundColor (Color?) - Optional circular background color. Default: null (transparent)

Size Constants:

• M3ELoadingIndicator.sizeXS - 28.0 pixels
• M3ELoadingIndicator.sizeSM - 32.0 pixels
• M3ELoadingIndicator.sizeMD - 40.0 pixels (default)
• M3ELoadingIndicator.sizeLG - 48.0 pixels
• M3ELoadingIndicator.sizeXL - 56.0 pixels

Migration from v1.x

⚠️ Breaking Change - Version 2.0.0

The M3ELoadingSize enum has been replaced with static const double values for better flexibility while maintaining named size convenience. This follows Flutter SDK conventions (Icon, CircularProgressIndicator patterns).

Before (v1.x):

M3ELoadingIndicator(size:M3ELoadingSize.xs)
M3ELoadingIndicator(size:M3ELoadingSize.md)
M3ELoadingIndicator(size:M3ELoadingSize.xl)

After (v2.0+):

M3ELoadingIndicator(size:M3ELoadingIndicator.sizeXS)
M3ELoadingIndicator(size:M3ELoadingIndicator.sizeMD)
M3ELoadingIndicator(size:M3ELoadingIndicator.sizeXL)
// Or use direct values for even more flexibilityM3ELoadingIndicator(size:28.0)
M3ELoadingIndicator(size:40.0)
M3ELoadingIndicator(size:56.0)

Migration Steps:

1. Find and replace: M3ELoadingSize. → M3ELoadingIndicator.size
2. Uppercase the size suffix (e.g., md → MD, xs → XS)
3. Or replace with direct double values

Performance

• Uses RepaintBoundary for optimized repaints
• Respects MediaQuery.disableAnimationsOf() for accessibility
• Efficient shouldRepaint logic in custom painter
• Smooth 60fps animations with spring physics

Platform Support

Platform	Supported
Android	✅
iOS	✅
Web	✅
macOS	✅
Linux	✅
Windows	✅

Example

See the example directory for a complete demo app.

To run the example:

cd example
flutter run

Dependencies

• androidx_graphics_shapes ^1.5.0 - Material shape morphing library

Credits

Inspired by Android's Material 3 Expressive loading indicators.

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please open an issue or PR on GitHub.