StreamBuilder<T> class

Widget that builds itself based on the latest snapshot of interaction with a Stream.

Managing the stream

The stream must have been obtained earlier, e.g. during State.initState, State.didUpdateWidget, or State.didChangeDependencies. It must not be created during the or method call when constructing the StreamBuilder. If the stream is created at the same time as the StreamBuilder, then every time the StreamBuilder's parent is rebuilt, the asynchronous task will be restarted.

A general guideline is to assume that every build method could get called every frame, and to treat omitted calls as an optimization.


Widget rebuilding is scheduled by each interaction, using State.setState, but is otherwise decoupled from the timing of the stream. The builder is called at the discretion of the Flutter pipeline, and will thus receive a timing-dependent sub-sequence of the snapshots that represent the interaction with the stream.

As an example, when interacting with a stream producing the integers 0 through 9, the builder may be called with any ordered sub-sequence of the following snapshots that includes the last one (the one with ConnectionState.done):

  • AsyncSnapshot<int>.withData(ConnectionState.waiting, null)
  • AsyncSnapshot<int>.withData(, 0)
  • AsyncSnapshot<int>.withData(, 1)
  • ...
  • AsyncSnapshot<int>.withData(, 9)
  • AsyncSnapshot<int>.withData(ConnectionState.done, 9)

The actual sequence of invocations of the builder depends on the relative timing of events produced by the stream and the build rate of the Flutter pipeline.

Changing the StreamBuilder configuration to another stream during event generation introduces snapshot pairs of the form:

  • AsyncSnapshot<int>.withData(ConnectionState.none, 5)
  • AsyncSnapshot<int>.withData(ConnectionState.waiting, 5)

The latter will be produced only when the new stream is non-null, and the former only when the old stream is non-null.

The stream may produce errors, resulting in snapshots of the form:

  • AsyncSnapshot<int>.withError(, 'some error', someStackTrace)

The data and error fields of snapshots produced are only changed when the state is

The initial snapshot data can be controlled by specifying initialData. This should be used to ensure that the first frame has the expected value, as the builder will always be called before the stream listener has a chance to be processed.

This sample shows a StreamBuilder that listens to a Stream that emits bids for an auction. Every time the StreamBuilder receives a bid from the Stream, it will display the price of the bid below an icon. If the Stream emits an error, the error is displayed below an error icon. When the Stream finishes emitting bids, the final price is displayed.

To create a local project with this code sample, run:
flutter create --sample=widgets.StreamBuilder.1 mysample

See also:



StreamBuilder({Key? key, T? initialData, required Stream<T>? stream, required AsyncWidgetBuilder<T> builder})
Creates a new StreamBuilder that builds itself based on the latest snapshot of interaction with the specified stream and whose build strategy is given by builder.


builder AsyncWidgetBuilder<T>
The build strategy currently used by this builder.
hashCode int
The hash code for this object.
no setterinherited
initialData → T?
The data that will be used to create the initial snapshot.
key Key?
Controls how one widget replaces another widget in the tree.
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
stream Stream<T>?
The asynchronous computation to which this builder is currently connected, possibly null. When changed, the current summary is updated using afterDisconnected, if the previous stream was not null, followed by afterConnected, if the new stream is not null.


afterConnected(AsyncSnapshot<T> current) AsyncSnapshot<T>
Returns an updated version of the current summary reflecting that we are now connected to a stream.
afterData(AsyncSnapshot<T> current, T data) AsyncSnapshot<T>
Returns an updated version of the current summary following a data event.
afterDisconnected(AsyncSnapshot<T> current) AsyncSnapshot<T>
Returns an updated version of the current summary reflecting that we are no longer connected to a stream.
afterDone(AsyncSnapshot<T> current) AsyncSnapshot<T>
Returns an updated version of the current summary following stream termination.
afterError(AsyncSnapshot<T> current, Object error, StackTrace stackTrace) AsyncSnapshot<T>
Returns an updated version of the current summary following an error with a stack trace.
build(BuildContext context, AsyncSnapshot<T> currentSummary) Widget
Returns a Widget based on the currentSummary.
createElement() StatefulElement
Creates a StatefulElement to manage this widget's location in the tree.
createState() State<StreamBuilderBase<T, AsyncSnapshot<T>>>
Creates the mutable state for this widget at a given location in the tree.
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
initial() AsyncSnapshot<T>
Returns the initial summary of stream interaction, typically representing the fact that no interaction has happened at all.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
toString({DiagnosticLevel minLevel =}) String
A string representation of this object.
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a string representation of this node and its descendants.
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) String
Returns a one-line detailed description of the object.
toStringShort() String
A short, textual description of this widget.


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