⏳ Flutter Loading Widgets #

A comprehensive Flutter package for loading states, progress indicators, and overlay components with cross-platform support.

✨ Features #

• 📱 Cross-platform: Native iOS/macOS and Material Design loading indicators
• 🎨 Customizable: Extensive styling options for all components
• 🔄 Multiple Types: Progress HUD, Loading Overlay, and custom indicators
• ♿ Accessible: Proper focus handling and accessibility support
• 🌍 Localizable: Full localization support for messages
• ⚡ Performance: Optimized for smooth animations and interactions
• 🎯 Flexible: Easy to integrate with existing loading states

📦 Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_loading_widgets: ^1.0.0

Then run:

flutter pub get

🚀 Quick Start #

import 'package:flutter_loading_widgets/flutter_loading_widgets.dart';

// Basic loading overlay
LoadingOverlay(
  isLoading: isProcessing,
  message: 'Loading...',
  child: YourContent(),
)

// Progress HUD
CustomProgressHud(
  isLoading: isProcessing,
  child: YourContent(),
)

// Extension method
YourContent().withLoadingOverlay(
  isLoading: isProcessing,
  message: 'Please wait...',
)

📖 Components #

LoadingOverlay #

A reusable loading overlay widget that shows a centered loading indicator with a semi-transparent background.

LoadingOverlay(
  isLoading: isProcessing,
  message: 'Processing your request...',
  child: YourContent(),
  // Customization options
  color: Colors.black.withOpacity(0.7),
  backgroundColor: Colors.white,
  borderRadius: 16.0,
  padding: EdgeInsets.all(32),
  dismissible: false,
)

CustomProgressHud #

A cross-platform progress HUD that shows platform-appropriate loading indicators.

CustomProgressHud(
  isLoading: isProcessing,
  child: YourContent(),
  // Customization options
  backgroundColor: Colors.black,
  opacity: 0.8,
  color: Colors.black,
  dismissible: true,
  onDismiss: () => cancelOperation(),
)

LoadingOverlayExtension #

An extension method to easily wrap any widget with loading overlay functionality.

// Using the extension
YourContent().withLoadingOverlay(
  isLoading: isProcessing,
  message: 'Loading data...',
  color: Colors.blue.withOpacity(0.5),
  backgroundColor: Colors.white,
  borderRadius: 20.0,
  dismissible: true,
  onDismiss: () => handleDismiss(),
)

🎛️ Configuration Options #

LoadingOverlay Properties #

CustomProgressHud Properties #

🎨 Customization Examples #

Custom Loading Theme #

class MyLoadingTheme {
  static const primaryColor = Color(0xFF6366F1);
  static const overlayColor = Color(0x80000000);
  
  static LoadingOverlay customLoadingOverlay({
    required bool isLoading,
    required Widget child,
    String? message,
  }) {
    return LoadingOverlay(
      isLoading: isLoading,
      message: message,
      child: child,
      color: overlayColor,
      backgroundColor: Colors.white,
      borderRadius: 20.0,
      padding: EdgeInsets.all(32),
      progressIndicator: CircularProgressIndicator(
        valueColor: AlwaysStoppedAnimation<Color>(primaryColor),
        strokeWidth: 3,
      ),
    );
  }
  
  static CustomProgressHud customProgressHud({
    required bool isLoading,
    required Widget child,
  }) {
    return CustomProgressHud(
      isLoading: isLoading,
      child: child,
      backgroundColor: overlayColor,
      opacity: 0.8,
      progressIndicator: CircularProgressIndicator(
        valueColor: AlwaysStoppedAnimation<Color>(primaryColor),
        strokeWidth: 4,
      ),
    );
  }
}

Custom Progress Indicators #

// Custom animated indicator
Widget customProgressIndicator() {
  return TweenAnimationBuilder<double>(
    duration: Duration(seconds: 2),
    tween: Tween(begin: 0.0, end: 1.0),
    builder: (context, value, child) {
      return CircularProgressIndicator(
        value: value,
        strokeWidth: 3,
        valueColor: AlwaysStoppedAnimation<Color>(Colors.blue),
      );
    },
  );
}

// Custom loading animation
Widget customLoadingAnimation() {
  return SizedBox(
    width: 50,
    height: 50,
    child: Stack(
      children: [
        Center(
          child: SizedBox(
            width: 30,
            height: 30,
            child: CircularProgressIndicator(
              strokeWidth: 2,
              valueColor: AlwaysStoppedAnimation<Color>(Colors.blue),
            ),
          ),
        ),
        Center(
          child: Icon(
            Icons.cloud_upload,
            color: Colors.blue,
            size: 20,
          ),
        ),
      ],
    ),
  );
}

State Management Integration #

// With Bloc/Cubit
class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return BlocBuilder<DataCubit, DataState>(
      builder: (context, state) {
        return LoadingOverlay(
          isLoading: state is DataLoading,
          message: state is DataLoading ? state.message : null,
          child: YourContent(),
        );
      },
    );
  }
}

// With Provider
class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Consumer<DataProvider>(
      builder: (context, provider, child) {
        return provider.isLoading
            ? LoadingOverlay(
                isLoading: true,
                message: provider.loadingMessage,
                child: YourContent(),
              )
            : YourContent();
      },
    );
  }
}

Form Loading States #

class LoginForm extends StatefulWidget {
  @override
  _LoginFormState createState() => _LoginFormState();
}

class _LoginFormState extends State<LoginForm> {
  bool _isLoading = false;
  
  Future<void> _handleLogin() async {
    setState(() => _isLoading = true);
    
    try {
      await authService.login(email, password);
      Navigator.pushReplacementNamed(context, '/home');
    } catch (e) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text('Login failed: $e')),
      );
    } finally {
      setState(() => _isLoading = false);
    }
  }
  
  @override
  Widget build(BuildContext context) {
    return LoadingOverlay(
      isLoading: _isLoading,
      message: 'Signing you in...',
      child: Scaffold(
        body: Padding(
          padding: EdgeInsets.all(16),
          child: Column(
            children: [
              TextField(/* email field */),
              TextField(/* password field */),
              ElevatedButton(
                onPressed: _isLoading ? null : _handleLogin,
                child: Text('Login'),
              ),
            ],
          ),
        ),
      ),
    );
  }
}

🌍 Localization #

All text properties support localization:

LoadingOverlay(
  isLoading: isProcessing,
  message: S.of(context).loadingMessage,
  child: YourContent(),
)

CustomProgressHud(
  isLoading: isProcessing,
  child: YourContent(),
)

📱 Platform Behavior #

iOS/macOS #

• Uses CupertinoActivityIndicator for native iOS styling
• Automatic platform-specific styling

Android/Other Platforms #

• Uses CircularProgressIndicator with Material Design styling
• Consistent with Material Design guidelines

🧪 Testing #

The package includes comprehensive tests. Run them with:

flutter test

🤝 Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments #

• Flutter team for the amazing framework
• Contributors and users who provide feedback

📞 Support #

If you encounter any problems or have suggestions, please file an issue at the GitHub repository.

Made with ❤️ for the Flutter community