AsyncValue<T> class abstract

A utility for safely manipulating asynchronous data.

By using AsyncValue, you are guaranteed that you cannot forget to handle the loading/error state of an asynchronous operation.

It also exposes some utilities to nicely convert an AsyncValue to a different object. For example, a Flutter Widget may use when to convert an AsyncValue into either a progress indicator, an error screen, or to show the data:

/// A provider that asynchronously exposes the current user
final userProvider = StreamProvider<User>((_) async* {
  // fetch the user

class Example extends ConsumerWidget {
  Widget build(BuildContext context, WidgetRef ref) {
    final AsyncValue<User> user =;

    return user.when(
      loading: () => CircularProgressIndicator(),
      error: (error, stack) => Text('Oops, something unexpected happened'),
      data: (user) => Text('Hello ${}'),

If a consumer of an AsyncValue does not care about the loading/error state, consider using value/valueOrNull to read the state:

Widget build(BuildContext context, WidgetRef ref) {
  // Reading .value will be throw during error and return null on "loading" states.
  final User user =;

  // Reading .value will be throw both on loading and error states.
  final User user2 =;


See also:

Available Extensions
  • @sealed
  • @immutable

Constructors value)
Creates an AsyncValue with a data.
AsyncValue.error(Object error, StackTrace stackTrace)
Creates an AsyncValue in the error state.
Creates an AsyncValue in loading state.


error Object?
The error.
no setter
hashCode int
The hash code for this object.
no setteroverride
hasValue bool
Whether value is set.
no setter
isLoading bool
Whether some new value is currently asynchronously loading.
no setter
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
stackTrace StackTrace?
The stacktrace of error.
no setter
value → T?
The value currently exposed.
no setter


copyWithPrevious(AsyncValue<T> previous, {bool isRefresh = true}) AsyncValue<T>
Clone an AsyncValue, merging it with previous.
map<R>({required R data(AsyncData<T> data), required R error(AsyncError<T> error), required R loading(AsyncLoading<T> loading)}) → R
Perform some action based on the current state of the AsyncValue.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
toString() String
A string representation of this object.
unwrapPrevious() AsyncValue<T>
The opposite of copyWithPrevious, reverting to the raw AsyncValue with no information on the previous state.


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

Static Methods

guard<T>(Future<T> future(), [bool test(Object)?]) Future<AsyncValue<T>>
Transforms a Future that may fail into something that is safe to read.