SmartStateHandler<T> class

A comprehensive state management widget that handles all common UI states with enhanced developer experience and flexible customization options.

This StatelessWidget provides a clean, predictable way to handle multiple UI states with animations, memoization, and efficient rebuilds.

Features:

  • Multiple state handling (initial, loading, error, empty, success, offline)
  • Smooth animations between state transitions
  • Memoized widgets to prevent unnecessary rebuilds
  • Pagination support with auto-scroll and debounced loading
  • Skeleton loading with shimmer support
  • Overlay mode for forms and non-intrusive state changes
  • Customizable icons, text, and widgets
  • Debug mode with comprehensive logging
  • Pull-to-refresh functionality
  • Error handling with snackbar integration

Example:

SmartStateHandler<List<Product>>(
  currentState: controller.state,
  successData: controller.products,
  onRetryPressed: controller.retry,
  onPullToRefresh: controller.refresh,
  onLoadMoreData: controller.loadMore,
  successDataBuilder: (context, products) => ProductGrid(products),
)
Inheritance

Constructors

SmartStateHandler({Key? key, required SmartState currentState, T? successData, dynamic errorObject, Widget successDataBuilder(BuildContext context, T data)?, VoidCallback? onRetryPressed, Future<void> onPullToRefresh()?, Future<void> onLoadMoreData()?, WidgetBuilder? initialStateBuilder, WidgetBuilder? loadingStateBuilder, Widget errorStateBuilder(BuildContext context, dynamic errorObject)?, WidgetBuilder? emptyStateBuilder, WidgetBuilder? offlineStateBuilder, WidgetBuilder? skeletonLoadingBuilder, bool enableOverlayStates = false, WidgetBuilder? baseContentBuilder, WidgetBuilder? overlayLoadingBuilder, Widget overlayErrorBuilder(BuildContext context, dynamic errorObject)?, WidgetBuilder? overlaySuccessBuilder, Alignment overlayAlignment = Alignment.center, Color? overlayBackgroundColor, bool hasMoreDataToLoad = true, dynamic paginationErrorObject, Widget paginationErrorStateBuilder(BuildContext context, dynamic errorObject)?, WidgetBuilder? loadMoreIndicatorBuilder, WidgetBuilder? noMoreDataIndicatorBuilder, double autoScrollThreshold = 100.0, int loadMoreDebounceMs = 300, bool enablePullToRefresh = true, bool enableSkeletonLoading = false, bool showErrorAsSnackbar = false, bool enableDebugLogs = false, bool enableAnimations = true, SmartStateAnimationConfig animationConfig = const SmartStateAnimationConfig(), Widget customTransitionBuilder(BuildContext context, Widget child, Animation<double> animation)?, SmartStateOverlayConfig overlayConfig = const SmartStateOverlayConfig(), VoidCallback? onOverlayDismiss, SmartStateSnackbarConfig snackbarConfig = const SmartStateSnackbarConfig(), IconData errorIcon = Icons.error_outline, IconData emptyIcon = Icons.inbox_outlined, IconData offlineIcon = Icons.wifi_off_outlined, IconData? loadingIcon, SmartStateTextConfig textConfig = const SmartStateTextConfig(), SmartStateWidgetConfig widgetConfig = const SmartStateWidgetConfig(), String? customLoadingMessage, Color? loadingIndicatorColor, Color? errorDisplayColor, Color? containerBackgroundColor, EdgeInsets? contentPadding, EdgeInsets? contentMargin})
const

Properties

animationConfig → SmartStateAnimationConfig
Animation configuration for state transitions
final
autoScrollThreshold → double
Threshold in pixels from bottom to trigger auto-scroll load more
final
baseContentBuilder → WidgetBuilder?
Builder for base content in overlay mode
final
containerBackgroundColor → Color?
Background color for the container
final
contentMargin → EdgeInsets?
Margin for content
final
contentPadding → EdgeInsets?
Padding for content
final
currentState → SmartState
The current state that determines which UI to show
final
customLoadingMessage → String?
Custom loading message to show contextual info
final
customTransitionBuilder → Widget Function(BuildContext context, Widget child, Animation<double> animation)?
Custom transition builder for state changes
final
emptyIcon → IconData
Icon for empty states
final
emptyStateBuilder → WidgetBuilder?
Custom builder for empty state UI
final
enableAnimations → bool
Enable animations between state transitions
final
enableDebugLogs → bool
Enable debug logging
final
enableOverlayStates → bool
Enable overlay mode where states appear above base content
final
enablePullToRefresh → bool
Enable pull-to-refresh functionality
final
enableSkeletonLoading → bool
Enable skeleton loading instead of regular loading
final
errorDisplayColor → Color?
Color for error displays
final
errorIcon → IconData
Icon for error states
final
errorObject → dynamic
Error information when currentState is error
final
errorStateBuilder → Widget Function(BuildContext context, dynamic errorObject)?
Custom builder for error state UI
final
hashCode → int
The hash code for this object.
no setterinherited
hasMoreDataToLoad → bool
Whether there's more data to load for pagination
final
initialStateBuilder → WidgetBuilder?
Custom builder for initial state UI
final
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
loadingIcon → IconData?
Optional icon for loading states
final
loadingIndicatorColor → Color?
Color for loading indicators
final
loadingStateBuilder → WidgetBuilder?
Custom builder for loading state UI
final
loadMoreDebounceMs → int
Debounce time in milliseconds for load more calls
final
loadMoreIndicatorBuilder → WidgetBuilder?
Custom builder for load more indicator
final
noMoreDataIndicatorBuilder → WidgetBuilder?
Custom builder for no more data indicator
final
offlineIcon → IconData
Icon for offline states
final
offlineStateBuilder → WidgetBuilder?
Custom builder for offline state UI
final
onLoadMoreData → Future<void> Function()?
Callback executed when user scrolls near bottom for pagination
final
onOverlayDismiss → VoidCallback?
Callback when overlay is dismissed (works with isDismissible)
final
onPullToRefresh → Future<void> Function()?
Callback executed when user pulls down to refresh
final
onRetryPressed → VoidCallback?
Callback executed when user presses retry button
final
overlayAlignment → Alignment
Alignment of overlay content
final
overlayBackgroundColor → Color?
Background color for overlay
final
overlayConfig → SmartStateOverlayConfig
Comprehensive overlay state configuration Controls which states show as overlays, dismissibility, and styling
final
overlayErrorBuilder → Widget Function(BuildContext context, dynamic errorObject)?
Custom builder for overlay error state
final
overlayLoadingBuilder → WidgetBuilder?
Custom builder for overlay loading state
final
overlaySuccessBuilder → WidgetBuilder?
Custom builder for overlay success state
final
paginationErrorObject → dynamic
Error object for pagination errors
final
paginationErrorStateBuilder → Widget Function(BuildContext context, dynamic errorObject)?
Custom builder for pagination error state
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
showErrorAsSnackbar → bool
Show errors as snackbar instead of replacing content
final
skeletonLoadingBuilder → WidgetBuilder?
Custom builder for skeleton loading UI
final
snackbarConfig → SmartStateSnackbarConfig
Comprehensive snackbar configuration Controls position (top/bottom), styling, and behavior
final
successData → T?
Data to display when currentState is success
final
successDataBuilder → Widget Function(BuildContext context, T data)?
Builder function that creates UI when data is successfully loaded
final
textConfig → SmartStateTextConfig
Configuration for all text content
final
widgetConfig → SmartStateWidgetConfig
Configuration for all widget content
final

Methods

build(BuildContext context) → Widget
Describes the part of the user interface represented by this widget.
override
createElement() → StatelessElement
Creates a StatelessElement to manage this widget's location in the tree.
inherited
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String
A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug, int wrapWidth = 65}) → String
Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String
Returns a one-line detailed description of the object.
inherited
toStringShort() → String
A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited