StreamProvider<T> class

Creates a stream and exposes its latest event.

StreamProvider is identical in behavior/usage to FutureProvider, modulo the fact that the value created is a Stream instead of a Future.

It can be used to express a value asynchronously loaded that can change over time, such as an editable Message coming from a web socket:

final messageProvider = StreamProvider.autoDispose<String>((ref) async* {
  // Open the connection
  final channel = IOWebSocketChannel.connect('ws://echo.websocket.org');

  // Close the connection when the stream is destroyed
  ref.onDispose(() => channel.sink.close());

  // Parse the value received and emit a Message instance
  await for (final value in channel.stream) {
    yield value.toString();
  }
});

Which the UI can then listen:

Widget build(BuildContext context, WidgetRef ref) {
  AsyncValue<String> message = ref.watch(messageProvider);

  return message.when(
    loading: () => const CircularProgressIndicator(),
    error: (err, stack) => Text('Error: $err'),
    data: (message) {
      return Text(message);
    },
  );
}

Note: When listening to web sockets, firebase, or anything that consumes resources, it is important to use StreamProvider.autoDispose instead of simply StreamProvider.

This ensures that the resources are released when no longer needed as, by default, a StreamProvider is almost never destroyed.

See also:

Inheritance
Mixed in types
Available Extensions

Constructors

StreamProvider(Stream<T> _createFn(StreamProviderRef<T> ref), {String? name, Iterable<ProviderOrFamily>? dependencies, @Deprecated('Will be removed in 3.0.0') Family<Object?>? from, @Deprecated('Will be removed in 3.0.0') Object? argument, @Deprecated('Will be removed in 3.0.0') DebugGetCreateSourceHash? debugGetCreateSourceHash})
Creates a stream and exposes its latest event.
StreamProvider.internal(Stream<T> _createFn(StreamProviderRef<T> ref), {required String? name, required Iterable<ProviderOrFamily>? dependencies, required Iterable<ProviderOrFamily>? allTransitiveDependencies, required DebugGetCreateSourceHash? debugGetCreateSourceHash, Family<Object?>? from, Object? argument})
An implementation detail of Riverpod

Properties

allTransitiveDependencies Iterable<ProviderOrFamily>?
All the dependencies of a provider and their dependencies too.
finalinherited
argument Object?
If this provider was created with the .family modifier, argument is the variable that was used.
finalinherited
debugGetCreateSourceHash → DebugGetCreateSourceHash?
A debug-only fucntion for obtaining a hash of the source code of the initialization function.
finalinherited
dependencies Iterable<ProviderOrFamily>?
The list of providers that this provider potentially depends on.
finalinherited
from Family<Object?>?
If this provider was created with the .family modifier, from is the .family instance.
finalinherited
future AlwaysAliveRefreshable<Future<T>>
latefinal
hashCode int
The hash code for this object.
no setterinherited
name String?
A custom label for providers.
finalinherited
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
stream AlwaysAliveRefreshable<Stream<T>>
latefinal

Methods

addListener(Node node, void listener(AsyncValue<T>? previous, AsyncValue<T> next), {required void onError(Object error, StackTrace stackTrace)?, required void onDependencyMayHaveChanged()?, required bool fireImmediately}) ProviderSubscription<AsyncValue<T>>
Starts listening to this transformer
inherited
createElement() StreamProviderElement<T>
An internal method that defines how a provider behaves.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
overrideWith(Create<Stream<T>, StreamProviderRef<T>> create) Override
Override the provider with a new initialization function.
read(Node node) AsyncValue<T>
Obtains the result of this provider expression without adding listener.
inherited
select<Selected>(Selected selector(AsyncValue<T> value)) AlwaysAliveProviderListenable<Selected>
Partially listen to a provider.
inherited
selectAsync<Output>(Output selector(T data)) AlwaysAliveProviderListenable<Future<Output>>
A variant of select for asynchronous values
inherited
toString() String
A string representation of this object.
inherited

Operators

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

Constants

autoDispose → const AutoDisposeStreamProviderBuilder
Marks the provider as automatically disposed when no longer listened to.
family → const StreamProviderFamilyBuilder
A group of providers that builds their value from an external parameter.