StreamBuilder: What It Is, How It Works, and Application in Flutter

What Is StreamBuilder

StreamBuilder is a widget from the Flutter SDK package that subscribes to a Stream and rebuilds its child element on every new stream event. StreamBuilder accepts a Stream object and returns a widget based on the latest snapshot received from the stream.

In Flutter architecture, StreamBuilder belongs to the group of Builder widgets that separate UI construction from data state. Unlike StatefulWidget, where changing state requires an explicit setState call, StreamBuilder reacts to async events automatically, simplifying code and reducing the risk of synchronization errors.

Unlike FutureBuilder, which handles a single async value, StreamBuilder is designed for continuous data streams. FutureBuilder terminates after receiving the first result, while StreamBuilder continues listening to the stream and updating the UI on every new event.

StreamBuilder is used in all scenarios where data arrives continuously: WebSocket connections, sensor callbacks, Firebase notifications, Bluetooth event queues, and application state broadcasting via BLoC. According to analysis of Flutter projects on GitHub (2025), StreamBuilder is among the top three most used Builder widgets alongside FutureBuilder and LayoutBuilder.

Bottom line: use StreamBuilder everywhere the UI needs to reflect continuously changing data, avoiding manual state management through StatefulWidget.

How StreamBuilder Works

StreamBuilder subscribes to a Stream at build time and unsubscribes when the widget is disposed. Each time the Stream emits an event, StreamBuilder receives a new AsyncSnapshot and calls the builder function to rebuild the UI.

The process consists of three stages. First: StreamBuilder creates a subscription to the passed Stream via the stream.listen method. Second: on each event, StreamBuilder updates the internal AsyncSnapshot and marks the widget as dirty for rebuilding. Third: the framework calls the builder function with the new snapshot, and the UI displays the current data.

Important: StreamBuilder uses StreamSubscription internally. If the Stream is passed directly, StreamBuilder subscribes once during initialization. If the Stream changes (for example, during a parent rebuild), StreamBuilder unsubscribes from the old stream and subscribes to the new one. This behavior is controlled by the initialData and buildWhen parameters, which allow optimizing the number of rebuilds.

Bottom line: understanding the subscription lifecycle is the foundation of proper StreamBuilder usage. Incorrect stream management leads to memory leaks or stale data in the UI.

ConnectionState: Four Stream States

The connectionState property of the AsyncSnapshot object determines which stage of stream processing the StreamBuilder is at. There are four states: none, waiting, active, done.

ConnectionState.none

None is the initial state when the Stream has not started transmitting data yet. In this state, snapshot.connectionState equals ConnectionState.none, and snapshot.data is null. Usually, a placeholder or waiting indicator is displayed in this state. If the Stream does not provide initial data, StreamBuilder starts in this state.

ConnectionState.waiting

Waiting is the state of waiting for data from an async stream. The Stream is active, but data has not arrived yet. This state occurs, for example, when loading data from the network or opening a long-lived connection. In this state, it is common to show a CircularProgressIndicator or skeleton loader.

ConnectionState.active

Active — the stream is emitting data, and the UI displays current information. In this state, snapshot.hasData is true, and snapshot.data contains the latest value from the stream. If the stream is a Broadcast Stream, the active state can coexist with waiting for new data.

ConnectionState.done

Done — the stream has completed, no new data will arrive. Snapshot.data contains the last value passed before the stream was closed. If the stream completed successfully, snapshot.hasError is false. This state is used to display the final result: a message like “Loading complete” or a transition to the next screen.

Bottom line: when building the UI through StreamBuilder, all four states must be handled so the interface correctly displays loading, data, errors, and completion.

Using StreamController to Manage the Stream

StreamController is a class from the dart:async package that creates and manages a Stream. StreamController allows adding data, handling errors, and closing the stream, controlling its lifecycle.

StreamController comes in two types: single-subscription (one subscriber) and broadcast (multiple subscribers). A single-subscription controller accepts only one listener at a time — a second subscription will throw an exception. A broadcast controller allows multiple StreamBuilder instances to listen to the same stream simultaneously, which is useful for BLoC and shared application state.

When creating a StreamController via StreamController<T>.broadcast(), data added before the first subscription is not replayed to new subscribers. To get the latest value upon connection, use BehaviourSubject from the rxdart package, which caches the last event.

After finishing work with the controller, you must call controller.close(). Not calling close leads to resource leaks: the stream remains open, subscribers stay in memory, and the GC does not free associated objects.

Bottom line: use StreamController with explicit lifecycle management. For single-subscription streams, use the standard controller; for shared state, use a broadcast controller or BehaviourSubject.

Code Examples with StreamBuilder

Example 1 demonstrates a countdown timer using StreamController and StreamBuilder.

import 'dart:async';

class TimerWidget extends StatefulWidget {
  const TimerWidget({super.key});

  final StreamController<int> controller = StreamController<int>();

  void startTimer() {
    int count = 0;
    Timer.periodic(Duration(seconds: 1), (timer) {
      controller.sink.add(count++);
      if (count > 10) {
        controller.close();
        timer.cancel();
      }
    });
  }
}

In the example, a controller is created to generate numbers from 0 to 10 at 1-second intervals. After reaching 10, close is called, and the stream terminates. StreamBuilder, subscribed to this controller's stream, will display each new value.

Example 2 — using StreamBuilder with a Broadcast Stream to display data from multiple sources.

final StreamController<String> broadcastController =
    StreamController<String>.broadcast();

StreamBuilder<String>(
  stream: broadcastController.stream,
  initialData: 'Waiting for data...',
  builder: (context, AsyncSnapshot<String> snapshot) {
    if (snapshot.connectionState == ConnectionState.waiting) {
      return const Center(
        child: CircularProgressIndicator(),
      );
    }
    if (snapshot.hasError) {
      return Text('Error: ${snapshot.error}');
    }
    return Text('Data: ${snapshot.data}');
  },
)

The second example shows handling all states: initialData for initial display, waiting for a loading indicator, hasError for errors, and data for success. This pattern is the standard for production code with StreamBuilder.

Bottom line: use initialData to avoid an empty screen at first, and always handle hasError to correctly display errors to the user.

Common Mistakes When Working with StreamBuilder

Mistake 1: creating a new Stream on every parent rebuild. If the Stream is passed through an expression that creates a new object on every build, StreamBuilder unsubscribes from the old one and subscribes to the new stream, causing an infinite rebuild loop. Solution: use a remembered variable or a StatefulWidget with a fixed Stream.

Mistake 2: lack of error handling. A Stream can emit errors via controller.sink.addError, and if the builder does not check snapshot.hasError, the user sees an empty screen or infinite loading. Solution: always check hasError and display a clear message.

Mistake 3: memory leaks due to an unclosed StreamController. If the controller is not closed in dispose, the stream continues to exist, and the GC does not free memory. Solution: call controller.close() in dispose and listen for the done event for final actions.

Mistake 4: using StreamBuilder with a slow builder function. Since the builder is called on every stream event, heavy computations inside it lead to frame drops. Solution: move computations to a separate isolate or use Stream.map for data transformation.

Bottom line: StreamBuilder is a powerful but demanding tool. Monitor the Stream lifecycle, handle errors, and avoid heavy operations in the builder.