LoadingStateHandlerWidget

A powerful Flutter widget for managing UI states with built-in retry functionality. This widget handles loading, error, empty, and normal states elegantly while providing a customizable retry mechanism with cooldown support.

Features

• 🔄 Smart state management (loading, error, empty, normal, data)
• ⏲️ Built-in retry mechanism with configurable cooldown
• 🎨 Fully customizable widgets for each state
• 🌐 Global default configurations
• ⚡ Optimized performance with const constructor
• 🎯 Type-safe callbacks and builders

Installation

Run the following command to add the package to your project:

flutter pub add loading_state_handler

or add the package to your pubspec.yaml file:

dependencies:
  loading_state_handler: ^2.1.0

Quick Start

// Set global defaults (optional)
LoadingStateHandlerWidget.setDefaults(
    defaultRetryCooldown: const Duration(seconds: 5),
    defaultErrorBuilder:
        (context, errorMessage, retryWidget, retryCooldown, onRetry) => Center(
      child: Column(
        spacing: 20,
        mainAxisAlignment: MainAxisAlignment.center,
        children: [
          Text(errorMessage ?? 'An error occurred'),
          retryWidget,
        ],
      ),
    ),
  );

// Use in your widget
LoadingStateHandlerWidget(
        currentState: currentState,
        onLoading: (defaultOnLoading, context, message) {
          /// Uncomment to use the default loading callback
          // defaultOnLoading?.call(context, message);
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(
              content: Text(message ?? 'Custom Loading...'),
            ),
          );
        },
        onData: (defaultOnData, context, message) {
          defaultOnData?.call(context, message);
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(
              content: Text(message ?? 'Custom Got Data...'),
            ),
          );
        },
        errorMessage: errorMessage,
        child: const Center(child: Text('Data Loaded Successfully!')),
      );

Advanced Usage

Retry Mechanism

The widget includes a sophisticated retry mechanism with cooldown:

LoadingStateHandlerWidget(
        // State control properties
        currentState: _currentState,

        // Custom messages for different states
        errorMessage: _errorMessage,
        emptyMessage: 'No data available',
        loadingMessage: 'Fetching data...',

        // Retry configuration
        enableRetry: true, // Enable the retry mechanism
        retryCooldown:
            const Duration(seconds: 3), // Custom cooldown per instance
        onRetry: () {
          // Callback executed when the retry button is pressed
          // This will be disabled during the cooldown period
          _fetchData();
        },

        // Content to display when in normal state (not loading/error/empty)
        child: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              const Text(
                'Data loaded successfully!',
                style: TextStyle(fontSize: 18),
              ),
              const SizedBox(height: 20),
              ElevatedButton(
                onPressed: _fetchData,
                child: const Text('Refresh Data'),
              ),
            ],
          ),
        ),
      );

Global Configuration

Set default behaviors for all instances:

LoadingStateHandlerWidget.setDefaults(
    defaultOnData: (context, message) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(
          content: Text(message ?? 'Default Got Data...'),
        ),
      );
    },

    defaultOnLoading: (context, message) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(
          content: Text(message ?? 'Default Loading...'),
        ),
      );
    },

    defaultLoadingBuilder: (context, loadingMessage) =>
        const Center(child: CircularProgressIndicator()),

    defaultErrorBuilder:
        (context, errorMessage, retryWidget, retryCooldown, onRetry) => Center(
      child: Text(
        'Custom Error: $errorMessage',
        style: const TextStyle(color: Colors.red),
      ),
    ),

    defaultEmptyBuilder: (context, emptyMessage) => const Center(
      child: Text('No Data Available'),
    ),
  );

State-Specific Callbacks

Handle different states with custom callbacks:

LoadingStateHandlerWidget(
  loading: isLoading,
  error: hasError,
  empty: isEmpty,
  onLoading: (defaultCallback, context, message) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text(message ?? 'Custom Loading...'),
      ),
    );
  },
  onError: (defaultCallback, context, message) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text(message ?? 'Custom Error...'),
      ),
    );
  },
  onEmpty: (defaultCallback, context, message) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text(message ?? 'Custom Empty...'),
      ),
    );
  },
  child: ContentWidget(),
);

Disable State Changes

Control widget behavior granularly:

LoadingStateHandlerWidget(
  disableWidgetChanges: false,
  disableErrorWidgetChanges: true,
  disableEmptyWidgetChanges: false,
  // ... other properties
);

State Change Callback

Track state transitions with the onStateChange callback:

LoadingStateHandlerWidget(
  currentState: currentState,
  onStateChange: (oldState, newState) {
    print('State changed from $oldState to $newState');
    // You can use this to log state transitions or trigger additional actions
  },
  child: YourContentWidget(),
);

Custom Child Builder

Customize the child widget based on the current state:

LoadingStateHandlerWidget(
  currentState: currentState,
  childBuilder: (context, currentState, child) {
    // Add a colored border based on the current state
    return Container(
      decoration: BoxDecoration(
        border: Border.all(
          color: _getStateColor(currentState),
          width: 2.0,
        ),
        borderRadius: BorderRadius.circular(8.0),
      ),
      padding: const EdgeInsets.all(16.0),
      child: child, // The original child widget
    );
  },
  child: YourContentWidget(),
);

// Helper method to get color based on state
Color _getStateColor(CurrentStateEnum state) {
  switch (state) {
    case CurrentStateEnum.normal: return Colors.grey;
    case CurrentStateEnum.loading: return Colors.blue;
    case CurrentStateEnum.data: return Colors.green;
    case CurrentStateEnum.empty: return Colors.amber;
    case CurrentStateEnum.error: return Colors.red;
    default: return Colors.grey;
  }
}

Properties

Example

Check out the example, retry example, and controller example for a complete demonstration of all features.

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.