Stream Builder

The StreamBuilder widget builds its UI based on the latest snapshot from a Stream. It’s ideal for showing data that changes over time, such as real-time updates from WebSockets, Firebase, or any other continuous data source. Whenever the stream emits new data, the StreamBuilder automatically rebuilds its child.

Core Concepts

a) Stream-Driven UI

A Stream provides a sequence of async values over time (data events, errors, completion).

The StreamBuilder:

• Listens to the provided Stream

• Receives a new snapshot whenever:

  • New data arrives

  • An error occurs

  • The stream completes

• Rebuilds its child every time the snapshot changes

This makes the UI directly driven by live stream events instead of manual updates.

b) Snapshot-Based Rendering

The child of StreamBuilder typically reads from a snapshot that can include:

• Current connection state (waiting, active, done)

• Latest data

• Any error emitted by the stream

You can use these to:

• Show a loading UI when the stream is connecting / waiting

• Show an error UI if there’s a problem

• Show live data UI when values are being received

Properties

Property	Description
Initial Data	The initial data that will be used to create the child widget before any data is received from the stream.
Controller	A StreamController variable or any app state variable that provides a stream to listen to.
On Success	An action to be executed when the stream emits a new value. Receives an object with streamState: 'listening', streamValue (the new data), and other stream information.
On Error	An action to be executed when the stream emits an error. Receives an object with streamState: 'error', error (the error details), and other stream information.

Child of StreamBuilder

Slot	Description
child	The widget to be rebuilt whenever the stream emits a new value. The child has access to streamState (e.g., 'loading', 'error', 'listening', 'completed'), streamValue (the latest data), and error (if an error occurred). You can access these variables directly by name or with the StreamBuilder name prefix: streamBuilderName.streamState.

Default Properties

The StreamBuilder widget supports only Layout section of Default Properties.

Use Cases

Use StreamBuilder when you need live / real-time or continuously updating UI, for example:

• Real-time feeds

  • Live chat messages

  • Activity feeds

  • Notifications stream

• Live data dashboards

  • Realtime analytics or metrics

  • Stock prices, crypto prices, or counters

  • Sensor or IoT readings

• Realtime backend updates

  • Firebase streams (Firestore, Realtime DB)

  • WebSocket subscriptions

  • Streaming APIs or event sources

Anywhere data keeps changing over time and you want the UI to react automatically, StreamBuilder fits.