riverpod_sugar library

🍯 Riverpod Sugar

A collection of lightweight widgets and utilities that reduce boilerplate and improve developer ergonomics when using flutter_riverpod.

Key Features:

  • RxWidget & RxBuilder: Cleaner widget definitions
  • AsyncValueSugar.easyWhen: Simplified async state handling
  • Sugar Extensions: Ultra-concise one-liner state management (like ScreenUtil)
  • Debouncer: Prevent rapid state updates from user input
  • FormManager: Easy form validation state tracking
  • RxStatefulWidget: Stateful version of RxWidget
  • Provider Combiners: Combine multiple providers elegantly

Ultra-Simple One-Liner Examples:

// Create providers instantly
final counter = 0.state;           // StateProvider<int>
final name = "John".text;          // StateProvider<String>
final isDark = false.toggle;       // StateProvider<bool>

// Use in widgets - no boilerplate!
class MyWidget extends RxWidget {
  @override
  Widget buildRx(BuildContext context, WidgetRef ref) {
    return Column(children: [
      ref.counter(counter),        // Display counter
      Text('${ref.watchValue(counter)}'),   // Your own design!
      ElevatedButton(onPressed: () => counter.increment(ref), child: Text('+')),
      Text('${ref.watchValue(name)}'),      // Full flexibility!
      ref.showEither(isDark, DarkWidget(), LightWidget()),     // Conditional widget
    ]);
  }
}

// Update state with descriptive method names
counter.increment(ref);         // Increment
name.updateText(ref, "Jane");   // Update text
isDark.toggle(ref);             // Toggle boolean

For comprehensive examples, see the /example folder.

Classes

AdvancedDebouncer
A more advanced debouncer that can handle different types of debouncing strategies.
AlwaysAliveRefreshable<T>
An interface for provider expressions that can be passed to ref.refresh
AsyncData<T>
Creates an AsyncValue with a data.
AsyncError<T>
Creates an AsyncValue in the error state.
AsyncLoading<T>
Creates an AsyncValue in loading state.
AsyncNotifier<State>
A Notifier implementation that is asynchronously initialized.
AsyncNotifierProviderElement<NotifierT extends AsyncNotifierBase<T>, T>
The element of AsyncNotifierProvider.
AsyncNotifierProviderElementBase<NotifierT extends AsyncNotifierBase<T>, T>
The element of AsyncNotifierProvider.
AsyncNotifierProviderFamily<NotifierT extends FamilyAsyncNotifier<T, Arg>, T, Arg>
The Family of AsyncNotifierProvider.
AsyncNotifierProviderRef<T>
An object used by providers to interact with other providers and the life-cycles of the application.
AsyncProviderCombiners
Utilities specifically for working with AsyncValue providers.
AsyncValue<T>
A utility for safely manipulating asynchronous data.
AutoDisposeAsyncNotifier<State>
A provider which creates and listens to an AsyncNotifier.
AutoDisposeAsyncNotifierProviderElement<NotifierT extends AsyncNotifierBase<T>, T>
The element of AutoDisposeAsyncNotifierProvider.
AutoDisposeAsyncNotifierProviderFamily<NotifierT extends AutoDisposeFamilyAsyncNotifier<T, Arg>, T, Arg>
The Family of AsyncNotifierProvider.
AutoDisposeAsyncNotifierProviderRef<T>
An object used by providers to interact with other providers and the life-cycles of the application.
AutoDisposeChangeNotifierProvider<NotifierT extends ChangeNotifier?>
Creates a ChangeNotifier and exposes its current state.
AutoDisposeChangeNotifierProviderElement<NotifierT extends ChangeNotifier?>
The element of AutoDisposeChangeNotifierProvider.
AutoDisposeChangeNotifierProviderFamily<NotifierT extends ChangeNotifier?, Arg>
The Family of AutoDisposeChangeNotifierProvider.
AutoDisposeChangeNotifierProviderRef<NotifierT extends ChangeNotifier?>
An object used by providers to interact with other providers and the life-cycles of the application.
AutoDisposeFamilyAsyncNotifier<State, Arg>
A provider which creates and listens to an AsyncNotifier.
AutoDisposeFamilyNotifier<State, Arg>
A class which exposes a state that can change over time.
AutoDisposeFamilyStreamNotifier<State, Arg>
A variant of AsyncNotifier which has build creating a Stream.
AutoDisposeFutureProvider<T>
A provider that asynchronously creates a value.
AutoDisposeFutureProviderElement<T>
The ProviderElementBase of AutoDisposeFutureProvider
AutoDisposeFutureProviderFamily<R, Arg>
The Family of an AutoDisposeFutureProvider
AutoDisposeFutureProviderRef<State>
An object used by providers to interact with other providers and the life-cycles of the application.
AutoDisposeNotifier<State>
A class which exposes a state that can change over time.
AutoDisposeNotifierProviderElement<NotifierT extends NotifierBase<T>, T>
The element of AutoDisposeNotifierProvider
AutoDisposeNotifierProviderFamily<NotifierT extends AutoDisposeFamilyNotifier<T, Arg>, T, Arg>
The Family of NotifierProvider.
AutoDisposeNotifierProviderRef<T>
An object used by providers to interact with other providers and the life-cycles of the application.
AutoDisposeProvider<T>
A provider that exposes a read-only value.
AutoDisposeProviderElement<T>
The element of AutoDisposeProvider
AutoDisposeProviderFamily<R, Arg>
The Family of AutoDisposeProvider
AutoDisposeProviderRef<State>
An object used by providers to interact with other providers and the life-cycles of the application.
AutoDisposeRef<State>
A Ref for providers that are automatically destroyed when no longer used.
AutoDisposeStateNotifierProvider<NotifierT extends StateNotifier<T>, T>
Creates a StateNotifier and exposes its current state.
AutoDisposeStateNotifierProviderElement<NotifierT extends StateNotifier<T>, T>
The element of AutoDisposeStateNotifierProvider.
AutoDisposeStateNotifierProviderFamily<NotifierT extends StateNotifier<T>, T, Arg>
The Family of AutoDisposeStateNotifierProvider.
AutoDisposeStateNotifierProviderRef<NotifierT extends StateNotifier<T>, T>
An object used by providers to interact with other providers and the life-cycles of the application.
AutoDisposeStateProvider<T>
A provider that exposes a value that can be modified from outside.
AutoDisposeStateProviderElement<T>
The element of StateProvider.
AutoDisposeStateProviderFamily<R, Arg>
The Family of StateProvider.
AutoDisposeStateProviderRef<State>
An object used by providers to interact with other providers and the life-cycles of the application.
AutoDisposeStreamNotifier<State>
A variant of AsyncNotifier which has build creating a Stream.
AutoDisposeStreamNotifierProviderElement<NotifierT extends AsyncNotifierBase<T>, T>
The element of AutoDisposeStreamNotifierProvider.
AutoDisposeStreamNotifierProviderFamily<NotifierT extends AutoDisposeFamilyStreamNotifier<T, Arg>, T, Arg>
The Family of StreamNotifierProvider.
AutoDisposeStreamNotifierProviderRef<T>
An object used by providers to interact with other providers and the life-cycles of the application.
AutoDisposeStreamProvider<T>
Creates a stream and exposes its latest event.
AutoDisposeStreamProviderElement<T>
The element of AutoDisposeStreamProvider.
AutoDisposeStreamProviderFamily<R, Arg>
The Family of AutoDisposeStreamProvider.
AutoDisposeStreamProviderRef<State>
An object used by providers to interact with other providers and the life-cycles of the application.
ChangeNotifierProvider<NotifierT extends ChangeNotifier?>
Creates a ChangeNotifier and exposes its current state.
ChangeNotifierProviderElement<NotifierT extends ChangeNotifier?>
The element of ChangeNotifierProvider.
ChangeNotifierProviderFamily<NotifierT extends ChangeNotifier?, Arg>
The Family of ChangeNotifierProvider.
ChangeNotifierProviderRef<NotifierT extends ChangeNotifier?>
An object used by providers to interact with other providers and the life-cycles of the application.
CommonValidators
Common validators that can be used with FormManager.
Consumer
Build a widget tree while listening to providers.
ConsumerState<T extends ConsumerStatefulWidget>
A State that has access to a WidgetRef through ref, allowing it to read providers.
ConsumerStatefulElement
The Element for a ConsumerStatefulWidget
ConsumerStatefulWidget
A StatefulWidget that can read providers.
ConsumerWidget
A StatelessWidget that can listen to providers.
Debouncer
A simple debouncer to delay the execution of a function.
Family<@Deprecated('The generic parameter will be removed in version 3.0.0. ' 'This is to enable riverpod_generator to implement families with generic parameters') State>
A base class for all families
FamilyAsyncNotifier<State, Arg>
A Notifier implementation that is asynchronously initialized.
FamilyNotifier<State, Arg>
A class which exposes a state that can change over time.
FamilyStreamNotifier<State, Arg>
A variant of AsyncNotifier which has build creating a Stream.
FormManager
A StateNotifier that manages form validation state.
FormState
State class that holds form validation information.
FutureProvider<T>
A provider that asynchronously creates a value.
FutureProviderElement<T>
The element of a FutureProvider
FutureProviderFamily<R, Arg>
The Family of a FutureProvider
FutureProviderRef<State>
An object used by providers to interact with other providers and the life-cycles of the application.
A object which maintains a provider alive.
Preset navigation transitions
Notifier<State>
A class which exposes a state that can change over time.
NotifierProviderElement<NotifierT extends NotifierBase<T>, T>
The element of NotifierProvider.
NotifierProviderFamily<NotifierT extends FamilyNotifier<T, Arg>, T, Arg>
The Family of NotifierProvider.
NotifierProviderRef<T>
An object used by providers to interact with other providers and the life-cycles of the application.
Override
An object used by ProviderContainer/ProviderScope to override the behavior of a provider/family for part of the application.
Provider<State>
A provider that exposes a read-only value.
ProviderBase<StateT>
A base class for all providers.
ProviderCombiners
Utility functions for combining multiple providers into single providers.
ProviderContainer
An object that stores the state of the providers and allows overriding the behavior of a specific provider.
ProviderElement<State>
A provider that exposes a read-only value.
ProviderElementBase<StateT>
An internal class that handles the state of a provider.
ProviderFamily<R, Arg>
The Family of Provider
ProviderListenableOrFamily
A shared interface between ProviderListenable and Family.
ProviderObserver
An object that listens to the changes of a ProviderContainer.
ProviderOrFamily
A common interface shared by ProviderBase and Family
ProviderRef<State>
An object used by providers to interact with other providers and the life-cycles of the application.
ProviderScope
A widget that stores the state of providers.
ProviderSubscription<State>
Represents the subscription to a ProviderListenable
RatingBar
A simple rating bar widget for demonstration
Ref<@Deprecated('Will be removed in 3.0') State extends Object?>
An object used by providers to interact with other providers and the life-cycles of the application.
Refreshable<T>
An interface for provider expressions that can be passed to ref.refresh
RxBuilder
A wrapper that provides a cleaner builder signature for inline reactive widgets.
RxShow
A conditional widget that shows/hides content based on a provider's value.
RxState<T extends ConsumerStatefulWidget>
The State class for RxStatefulWidget.
RxStatefulWidget
An abstract base class for stateful widgets that need to consume providers.
RxWidget
An abstract base class for a ConsumerWidget that simplifies the build method.
StateController<T>
A StateNotifier that allows modifying its state from outside.
StateNotifier<T>
An observable class that stores a single immutable state.
StateNotifierProvider<NotifierT extends StateNotifier<T>, T>
Creates a StateNotifier and exposes its current state.
StateNotifierProviderElement<NotifierT extends StateNotifier<T>, T>
The element of StateNotifierProvider.
StateNotifierProviderFamily<NotifierT extends StateNotifier<T>, T, Arg>
The Family of StateNotifierProvider.
StateNotifierProviderRef<NotifierT extends StateNotifier<T>, T>
An object used by providers to interact with other providers and the life-cycles of the application.
StateProvider<T>
A provider that exposes a value that can be modified from outside.
StateProviderElement<T>
The element of StateProvider.
StateProviderFamily<R, Arg>
The Family of StateProvider.
StateProviderRef<State>
An object used by providers to interact with other providers and the life-cycles of the application.
StateProviderRefAccess<T>
Helper class to provide ref-style access to StateProvider operations This enables syntax like: counterProvider.ref.watch(ref) and nameProvider.ref.set(ref, "value")
StreamNotifier<State>
A variant of AsyncNotifier which has build creating a Stream.
StreamNotifierProviderElement<NotifierT extends AsyncNotifierBase<T>, T>
The element of StreamNotifierProvider.
StreamNotifierProviderFamily<NotifierT extends FamilyStreamNotifier<T, Arg>, T, Arg>
The Family of StreamNotifierProvider.
StreamNotifierProviderRef<T>
An object used by providers to interact with other providers and the life-cycles of the application.
StreamProvider<T>
Creates a stream and exposes its latest event.
StreamProviderElement<T>
The element of StreamProvider.
StreamProviderFamily<R, Arg>
The Family of StreamProvider.
StreamProviderRef<State>
An object used by providers to interact with other providers and the life-cycles of the application.
SugarDebugger
Enhanced debugging and error handling utilities for Riverpod Sugar
SugarErrorHandler
Error handling utilities
SugarErrorReporter
Error reporter for Sugar operations
SugarNavigation
Static helper for setting up navigation
SugarPerformance
Performance monitoring for Sugar operations
SugarSafeOps
Safe operations wrapper that handles errors gracefully
SugarShowcase
Main showcase widget demonstrating all Sugar features
SugarValidator
Comprehensive validation utilities for Riverpod Sugar operations to provide better error messages and prevent common mistakes.
SugarValidators
Common validators for Sugar extensions
UncontrolledProviderScope
Expose a ProviderContainer to the widget tree.
WidgetRef
An object that allows widgets to interact with providers.

Mixins

AlwaysAliveProviderBase<State>
A base class for providers that never dispose themselves.
AlwaysAliveProviderListenable<State>
A base class for all providers, used to consume a provider.
OverrideWithValueMixin<State>
A mixin to add overrideWithValue capability to a provider.
ProviderListenable<State>
A base class for all providers, used to consume a provider.

Extensions

AsyncValueSugar on AsyncValue<T>
Extensions on AsyncValue to provide simpler ways to handle loading, error, and data states in the UI.
AsyncValueX on AsyncValue<T>
An extension that adds methods like when to an AsyncValue.
BooleanSugar on bool
Extension on booleans to create state providers instantly
BoolProviderSugar on StateProvider<bool>
Extension on StateProvider<bool> for boolean operations
ColorProviderSugar on StateProvider<Color>
Color provider manipulation extensions
ColorSugar on Color
Additional Sugar Extensions for Complex Types Adds support for Colors, ThemeData, Controllers, and Maps Extension on Color to create instant providers
DateTimeProviderSugar on StateProvider<DateTime>
DateTime provider manipulation extensions
DateTimeSugar on DateTime
Extension on DateTime to create instant providers
DoubleProviderSugar on StateProvider<double>
Extension on StateProvider<double> for decimal operations
DoubleSugar on double
Extension on double to create instant providers
EnumSugar on T
Extension on Enum to create instant providers
FocusNodeProviderSugar on StateProvider<FocusNode>
FocusNode provider manipulation extensions
FocusNodeSugar on FocusNode
Extension on FocusNode to create instant providers
IntProviderSugar on StateProvider<int>
Extension on StateProvider<int> for integer operations
ListProviderSugar on StateProvider<List<T>>
List provider manipulation extensions
ListSugar on List<T>
Extension on List to create instant providers
LocaleSugar on Locale
Extension on Locale to create instant providers
MapProviderSugar on StateProvider<Map<K, V>>
Map provider manipulation extensions
MapSugar on Map<K, V>
Extension on Map to create instant providers
Navigation extensions that make routing with state management incredibly simple Inspired by the same philosophy as our Sugar extensions - concise and intuitive Extension on WidgetRef to provide navigation sugar methods
NumberSugar on num
Ultra-concise extensions that make Riverpod state management one-liner. Inspired by ScreenUtil's .r, .sp, .w, .h approach for maximum simplicity. Extension on numbers to create state providers instantly
OverrideWithProviderExtension on ProviderType
A mixin to add overrideWithProvider capability to providers.
PageControllerProviderSugar on StateProvider<PageController>
PageController provider manipulation extensions
PageControllerSugar on PageController
Extension on PageController to create instant providers
ProviderCombinerExtensions on ProviderListenable<T>
Extensions on providers to make combining easier and more fluent.
PushableWidget on Widget
Extension on Widget to make it easily pushable
SafeIntProviderSugar on StateProvider<int>
Enhanced integer provider extensions with bounds checking
SafeListProviderSugar on StateProvider<List<T>>
Enhanced list provider extensions with validation
SafeStateProviderSugar on StateProvider<T>
Enhanced Sugar extensions with better error handling and validation
SafeStringProviderSugar on StateProvider<String>
Enhanced string provider extensions with validation
ScrollControllerProviderSugar on StateProvider<ScrollController>
ScrollController provider manipulation extensions
ScrollControllerSugar on ScrollController
Extension on ScrollController to create instant providers
SetProviderSugar on StateProvider<Set<T>>
Set provider manipulation extensions
SetSugar on Set<T>
Extension on Set to create instant providers
StateProviderDebugging on StateProvider<T>
Enhanced StateProvider extensions with debugging support
StateProviderRefFix on StateProvider<T>
Enhanced StateProvider operations with proper ref type handling
StateProviderSugar on StateProvider<T>
Extension on StateProvider for ultra-simple operations
StringProviderSugar on StateProvider<String>
Extension on StateProvider<String> for text operations
StringSugar on String
Extension on strings to create state providers instantly
TabControllerProviderSugar on StateProvider<TabController>
TabController provider manipulation extensions
TabControllerSugar on TabController
Extension on TabController to create instant providers
TextControllerProviderSugar on StateProvider<TextEditingController>
TextEditingController provider manipulation extensions
TextControllerSugar on TextEditingController
Extension on TextEditingController to create instant providers
ThemeDataProviderSugar on StateProvider<ThemeData>
ThemeData provider manipulation extensions
ThemeDataSugar on ThemeData
Extension on ThemeData to create instant providers
TimeOfDayProviderSugar on StateProvider<TimeOfDay>
TimeOfDay provider manipulation extensions
TimeOfDaySugar on TimeOfDay
Extension on TimeOfDay to create instant providers
WidgetRefSugar on WidgetRef
Extension on WidgetRef for enhanced state watching and management

Properties

counter → StateProvider<int>
Comprehensive examples showcasing all Riverpod Sugar features This file serves as both documentation and testing for the library Counter provider for demonstration
final
isDarkMode → StateProvider<bool>
Dark mode toggle provider
final
isLoading → StateProvider<bool>
Loading state provider
final
notifications → StateProvider<bool>
Notifications enabled provider
final
rating → StateProvider<double>
Rating provider
final
selectedColor → StateProvider<List<Color>>
Color selection provider using extension syntax
final
todos → StateProvider<List<String>>
Todo list provider
final
userName → StateProvider<String>
User name provider for demonstration
final
volume → StateProvider<double>
Volume control provider (using .state for any double)
final

Functions

describeIdentity(Object? object) → String
Returns a summary of the runtime type and hash code of object.
main() → void
A simple showcase of all Sugar features
shortHash(Object? object) → String
Object.hashCode's 20 least-significant bits.

Typedefs

AsyncNotifierFamilyProvider<NotifierT extends FamilyAsyncNotifier<T, Arg>, T, Arg> = FamilyAsyncNotifierProviderImpl<NotifierT, T, Arg>
A provider which creates and listens to an AsyncNotifier.
AsyncNotifierProvider<NotifierT extends AsyncNotifier<T>, T> = AsyncNotifierProviderImpl<NotifierT, T>
A provider which creates and listens to an AsyncNotifier.
AutoDisposeAsyncNotifierProvider<NotifierT extends AutoDisposeAsyncNotifier<T>, T> = AutoDisposeAsyncNotifierProviderImpl<NotifierT, T>
A provider which creates and listens to an AsyncNotifier.
AutoDisposeFamilyAsyncNotifierProvider<NotifierT extends AutoDisposeFamilyAsyncNotifier<T, Arg>, T, Arg> = AutoDisposeFamilyAsyncNotifierProviderImpl<NotifierT, T, Arg>
A provider which creates and listens to an AsyncNotifier.
AutoDisposeFamilyNotifierProvider<NotifierT extends AutoDisposeFamilyNotifier<T, Arg>, T, Arg> = AutoDisposeFamilyNotifierProviderImpl<NotifierT, T, Arg>
A Provider which exposes a Notifier and listens to it.
AutoDisposeFamilyStreamNotifierProvider<NotifierT extends AutoDisposeFamilyStreamNotifier<T, Arg>, T, Arg> = AutoDisposeFamilyStreamNotifierProviderImpl<NotifierT, T, Arg>
AutoDisposeNotifierProvider<NotifierT extends AutoDisposeNotifier<T>, T> = AutoDisposeNotifierProviderImpl<NotifierT, T>
A Provider which exposes a Notifier and listens to it.
AutoDisposeStreamNotifierProvider<NotifierT extends AutoDisposeStreamNotifier<T>, T> = AutoDisposeStreamNotifierProviderImpl<NotifierT, T>
ConsumerBuilder = Widget Function(BuildContext context, WidgetRef ref, Widget? child)
A function that can also listen to providers
ErrorListener = void Function(Object error, StackTrace? stackTrace)
A callback that can be passed to StateNotifier.onError.
Locator = T Function<T>()
A function that allows obtaining other objects.
NotifierFamilyProvider<NotifierT extends FamilyNotifier<T, Arg>, T, Arg> = FamilyNotifierProviderImpl<NotifierT, T, Arg>
The provider for NotifierProviderFamily.
NotifierProvider<NotifierT extends Notifier<T>, T> = NotifierProviderImpl<NotifierT, T>
A Provider which exposes a Notifier and listens to it.
RemoveListener = void Function()
A callback that can be used to remove a listener added with StateNotifier.addListener.
StreamNotifierFamilyProvider<NotifierT extends FamilyStreamNotifier<T, Arg>, T, Arg> = FamilyStreamNotifierProviderImpl<NotifierT, T, Arg>
A variant of AsyncNotifier which has build creating a Stream.
StreamNotifierProvider<NotifierT extends StreamNotifier<T>, T> = StreamNotifierProviderImpl<NotifierT, T>
A variant of AsyncNotifier which has build creating a Stream.
Validator<T> = String? Function(T value)
A function that validates a value and returns an error message if invalid.

Exceptions / Errors

CircularDependencyError
An error thrown when a call to Ref.read/Ref.watch leads to a provider depending on itself.
DependencyNotFoundException<T>
Thrown when tried to call LocatorMixin.read<T>(), but the T was not found.s
StateNotifierListenerError
An error thrown when trying to update the state of a StateNotifier, but at least one of the listeners threw.