Streams are one of the most important asynchronous programming concepts in Dart.
While a Future produces a single asynchronous result, a Stream can deliver multiple values over time.
For example:
Future
↓
One Result
Whereas:
Stream
↓
Value 1
↓
Value 2
↓
Value 3
↓
...
Streams are commonly used in Flutter and Dart for:
- Real-time data
- Database changes
- WebSocket messages
- Authentication state
- User events
- File processing
- Device sensors
- Notifications
- State updates
However, not every Dart stream behaves the same way.
Two important types are:
Single-subscription streams and broadcast streams.
The main difference is simple:
Single-Subscription Stream
↓
One Listener
Broadcast Stream
↓
Multiple Listeners
That sounds straightforward, but choosing the wrong type can cause runtime errors, missed events, unnecessary complexity, or incorrect application behavior.
This guide explains how both stream types work and when you should use each one.
What Is a Stream in Dart?
A Dart Stream represents a sequence of asynchronous events.
Consider:
Stream<int> countNumbers() async* {
for (int i = 1; i <= 5; i++) {
await Future.delayed(
const Duration(seconds: 1),
);
yield i;
}
}
Listening to it:
countNumbers().listen((value) {
print(value);
});
Output:
1
2
3
4
5
Unlike a Future, the stream does not complete after delivering its first value.
It continues producing events until the stream is closed or finishes.
Future vs Stream
A simple comparison:
| Feature | Future | Stream |
|---|---|---|
| Number of values | One | Multiple |
| Async operation | Yes | Yes |
| Can listen continuously | No | Yes |
| Typical use | API request | Real-time updates |
| Completion | One result/error | Multiple events then completion |
For example:
Future<User> getUser();
might fetch one user.
Meanwhile:
Stream<List<Message>> watchMessages();
might continuously provide new message data.
Two Main Stream Types in Dart
Dart streams can broadly be divided into:
Stream
│
├── Single-Subscription
│
└── Broadcast
Their primary difference is how many listeners can subscribe.
A single-subscription stream normally allows one listener.
A broadcast stream allows multiple listeners.
What Is a Single-Subscription Stream?
A single-subscription stream is designed to have one listener.
For example:
final controller =
StreamController<int>();
By default, StreamController creates a single-subscription stream.
You can listen:
controller.stream.listen((value) {
print('Listener: $value');
});
Then add events:
controller.add(10);
controller.add(20);
controller.add(30);
Output:
Listener: 10
Listener: 20
Listener: 30
This works perfectly.
What Happens with a Second Listener?
Consider:
final stream = controller.stream;
stream.listen((value) {
print('Listener 1: $value');
});
stream.listen((value) {
print('Listener 2: $value');
});
A single-subscription stream cannot normally be listened to a second time.
You can encounter an error similar to:
Bad state:
Stream has already been listened to.
This is one of the most common stream-related errors Dart developers encounter.
Why Does Single-Subscription Exist?
At first, broadcast streams may seem better because they support more listeners.
However, many asynchronous data sources represent a single sequence of events.
For example:
Open File
↓
Read Chunk 1
↓
Read Chunk 2
↓
Read Chunk 3
↓
Complete
This sequence naturally belongs to one consumer.
Single-subscription streams can also support lifecycle behavior such as pausing and resuming consumption.
They are useful when events represent a continuous operation rather than independent notifications to many observers.
Creating a Single-Subscription Stream
The simplest approach is:
final controller =
StreamController<String>();
Then:
controller.stream.listen((data) {
print(data);
});
Add data:
controller.add('Flutter');
controller.add('Dart');
Finally:
await controller.close();
async* Streams Are Commonly Single-Subscription
Consider:
Stream<int> generateNumbers() async* {
for (int i = 1; i <= 3; i++) {
yield i;
}
}
Usage:
final stream = generateNumbers();
stream.listen(print);
This type of generated stream represents one asynchronous sequence and is normally single-subscription.
What Is a Broadcast Stream?
A broadcast stream allows multiple listeners to subscribe to the same stream.
For example:
final controller =
StreamController<int>.broadcast();
Now multiple listeners are allowed:
controller.stream.listen((value) {
print('Listener A: $value');
});
controller.stream.listen((value) {
print('Listener B: $value');
});
Then:
controller.add(100);
Both active listeners receive the event:
Listener A: 100
Listener B: 100
This is the core behavior of a broadcast stream.
Visual Difference
Single-subscription:
Stream
↓
Listener A
Broadcast:
Stream
↙ ↓ ↘
Listener A B Listener C
This makes broadcast streams useful for event-style systems where several parts of an application may be interested in the same event.
Single-Subscription vs Broadcast Streams
| Feature | Single-Subscription | Broadcast |
|---|---|---|
| Listeners | One | Multiple |
Default StreamController | Yes | No |
Created with .broadcast() | No | Yes |
| Event distribution | One subscriber | All active subscribers |
| Suitable for event buses | Usually no | Yes |
| Suitable for sequential operations | Yes | Less typical |
| Late listener receives previous events | No | No by default |
| Independent listeners | No | Yes |
| Pause behavior | Can affect source flow | Per-subscription behavior differs |
The correct choice depends on what the stream represents.
Broadcast Streams Do Not Automatically Replay Old Events
This is extremely important.
Suppose:
final controller =
StreamController<int>.broadcast();
Then:
controller.add(10);
Afterward:
controller.stream.listen((value) {
print(value);
});
You should not expect the new listener to automatically receive:
10
Broadcast streams normally deliver events to listeners that are subscribed when the event occurs.
Think of them more like live radio:
Event 1
Event 2
Listener joins here
Event 3
Event 4
The listener receives:
Event 3
Event 4
not automatically:
Event 1
Event 2
Event 3
Event 4
Broadcast Does Not Mean Cached State
Developers sometimes expect:
StreamController<User>.broadcast();
to remember the latest User.
It does not.
A broadcast stream is primarily an event distribution mechanism, not automatically a state store.
If your UI needs the latest state immediately when subscribing, you need an architecture that explicitly retains that state.
Event vs State
Understanding this distinction makes stream architecture much easier.
An event might be:
UserLoggedOut
PaymentCompleted
NotificationReceived
ConnectionLost
These represent things that happened.
State might be:
Current User
Current Cart
Current Theme
Current Connection Status
Current Product List
State usually needs a current value.
A plain broadcast stream does not automatically preserve that latest value for future listeners.
Creating Broadcast Streams
Use:
final controller =
StreamController<String>.broadcast();
Listen from multiple places:
final subscriptionA =
controller.stream.listen((event) {
print('A received $event');
});
final subscriptionB =
controller.stream.listen((event) {
print('B received $event');
});
Send:
controller.add('Hello');
Output:
A received Hello
B received Hello
Practical Flutter Example
Suppose your application receives global connectivity events.
Multiple features may care about them:
Home Screen
Upload Manager
Sync Manager
Chat Manager
A broadcast-style stream can distribute:
Online
Offline
Online
to multiple subscribers.
Conceptually:
Connectivity Service
↓
Broadcast Stream
↙ ↓ ↘
Home Sync Upload
Each listener reacts independently.
Example Connectivity Service
A simplified service could look like:
class ConnectivityService {
final StreamController<bool>
_controller =
StreamController<bool>.broadcast();
Stream<bool> get statusStream =>
_controller.stream;
void updateStatus(bool isOnline) {
_controller.add(isOnline);
}
Future<void> dispose() async {
await _controller.close();
}
}
Now:
connectivityService.statusStream.listen(
(isOnline) {
print('Home: $isOnline');
},
);
and:
connectivityService.statusStream.listen(
(isOnline) {
print('Sync: $isOnline');
},
);
can coexist.
Practical Single-Subscription Example
Imagine reading a large file.
Conceptually:
File
↓
Chunk 1
↓
Chunk 2
↓
Chunk 3
↓
Chunk 4
↓
Consumer
There is one logical consumer processing the sequence.
A single-subscription stream naturally represents this operation.
Another example could be an asynchronous generator:
Stream<String> processItems(
List<String> items,
) async* {
for (final item in items) {
await Future.delayed(
const Duration(milliseconds: 300),
);
yield item;
}
}
Then:
await for (final item
in processItems(items)) {
print(item);
}
This represents one sequential asynchronous process.
listen() and StreamSubscription
When you call:
stream.listen(...);
Dart returns a:
StreamSubscription<T>
For example:
final subscription =
stream.listen((event) {
print(event);
});
You can then control that subscription.
subscription.pause();
Resume:
subscription.resume();
Cancel:
await subscription.cancel();
Managing subscriptions properly is particularly important in Flutter widgets and long-lived services.
Single-Subscription Streams Can Be Paused
A major property of single-subscription streams is that their single listener can pause its subscription.
For example:
final subscription =
controller.stream.listen((event) {
print(event);
});
subscription.pause();
Later:
subscription.resume();
Depending on the source, pausing may cause events to be buffered or may allow the underlying producer to slow or pause.
This can be useful for sequential data processing.
Broadcast Subscription Pausing
With broadcast streams, listeners are independent.
Imagine:
Broadcast Stream
↙ ↘
Listener A Listener B
If Listener A pauses, Listener B should not automatically stop receiving events.
Conceptually:
Event
↓
Listener A → Paused
Listener B → Receives Event
This is another reason broadcast streams fit independent observers.
Converting a Stream to Broadcast
An existing stream can be converted using:
final broadcastStream =
originalStream.asBroadcastStream();
Then:
broadcastStream.listen(
(event) {
print('Listener A: $event');
},
);
broadcastStream.listen(
(event) {
print('Listener B: $event');
},
);
However, do not use:
asBroadcastStream()
automatically just because you encountered:
Stream has already been listened to
First understand why the same stream is receiving multiple listeners.
Sometimes the real problem is incorrect architecture or duplicate subscriptions.
StreamController.broadcast() vs asBroadcastStream()
These two approaches solve related but different problems.
StreamController.broadcast()
Use this when you control the event producer.
final controller =
StreamController<Event>.broadcast();
You explicitly create a broadcast event source.
asBroadcastStream()
Use this when you already have a stream and need multiple listeners.
final sharedStream =
existingStream.asBroadcastStream();
This wraps an existing stream with broadcast-style subscription behavior.
Common Flutter Error: Stream Already Listened To
You may encounter:
Bad state:
Stream has already been listened to.
Consider:
final stream = repository.getMessages();
StreamBuilder(
stream: stream,
builder: ...,
);
Then somewhere else:
stream.listen(...);
If stream is single-subscription, the second subscription fails.
You need to determine whether:
A. Only one listener should exist
or
B. The data genuinely needs multiple listeners
If multiple independent listeners are part of the design, a broadcast/shared stream may be appropriate.
StreamBuilder with Streams
Flutter provides StreamBuilder for rebuilding UI in response to stream events.
Example:
StreamBuilder<List<Message>>(
stream: repository.watchMessages(),
builder: (context, snapshot) {
if (snapshot.hasError) {
return const Text(
'Something went wrong',
);
}
if (!snapshot.hasData) {
return const CircularProgressIndicator();
}
final messages = snapshot.data!;
return ListView.builder(
itemCount: messages.length,
itemBuilder: (context, index) {
return Text(
messages[index].text,
);
},
);
},
);
Whether the underlying stream should be single-subscription or broadcast depends on its source and how many consumers need it.
Avoid Creating Streams Repeatedly in build()
A common mistake is:
@override
Widget build(BuildContext context) {
final stream =
repository.createStream();
return StreamBuilder(
stream: stream,
builder: ...,
);
}
If createStream() starts new work every time, widget rebuilds may repeatedly create subscriptions or restart expensive operations.
Instead, create or obtain the stream at the correct lifecycle level.
For a StatefulWidget, that may mean:
late final Stream<Data> stream;
@override
void initState() {
super.initState();
stream = repository.watchData();
}
Then:
StreamBuilder(
stream: stream,
builder: ...,
);
The exact solution depends on the source, but avoid unintentionally recreating asynchronous work during every build.
Broadcast Streams for Global Events
Broadcast streams are particularly suitable for global event notifications.
For example:
enum AppEvent {
loggedOut,
profileUpdated,
cartUpdated,
}
Create:
class AppEventBus {
final _controller =
StreamController<AppEvent>.broadcast();
Stream<AppEvent> get stream =>
_controller.stream;
void emit(AppEvent event) {
_controller.add(event);
}
Future<void> dispose() async {
await _controller.close();
}
}
Now several application components can subscribe.
AppEventBus
↓
profileUpdated
↙ ↓ ↘
Home Profile Header
Use global event buses carefully, though. Excessive global events can make application state difficult to trace.
Broadcast Streams and WebSockets
WebSockets commonly produce continuous events:
Server
↓
Message A
↓
Message B
↓
Message C
If several parts of the application need the same connection events:
Chat Screen
Notification Service
Unread Counter
a shared broadcast layer can be useful.
Conceptually:
WebSocket
↓
Connection Service
↓
Broadcast Stream
↙ ↓ ↘
Chat Badge Notifications
This can prevent each feature from unnecessarily opening its own connection.
Broadcast Streams and Firebase
Many Firebase APIs expose streams for real-time data.
For example, Firestore can provide snapshots over time.
FirebaseFirestore.instance
.collection('messages')
.snapshots();
Your application may then transform those events:
Stream<List<Message>> watchMessages() {
return FirebaseFirestore.instance
.collection('messages')
.snapshots()
.map(
(snapshot) => snapshot.docs
.map(
(doc) => Message.fromJson(
doc.data(),
),
)
.toList(),
);
}
Do not automatically convert every Firebase stream to broadcast. Understand the behavior of the stream returned by the specific API and your application’s subscription requirements first.
Broadcast Streams for Authentication Events
An authentication service might expose:
Logged In
Logged Out
Token Expired
Session Restored
Multiple components may care about authentication changes.
For example:
Authentication Stream
↙ ↓ ↘
Router Profile Analytics
A multi-listener stream can be useful here.
However, authentication is also application state, so make sure newly created consumers can determine the current authentication state rather than relying only on events that occurred before they subscribed.
Single-Subscription Streams for Data Processing
Single-subscription streams are often a natural fit for sequential data pipelines.
For example:
Source
↓
Decode
↓
Validate
↓
Transform
↓
Save
A single consumer processes each event in order.
Examples include:
- Reading files
- Parsing data
- Processing downloads
- Sequential transformations
- Command output
- One-consumer async generators
The one-listener restriction can actually communicate the intended ownership of the operation.
Stream Transformations
Both stream types can use common transformations.
For example:
stream
.where((value) => value > 10)
.map((value) => value * 2)
.listen(print);
Given:
5
10
15
20
the resulting values are:
30
40
Other useful stream methods include:
map()
where()
take()
skip()
distinct()
asyncMap()
handleError()
The transformation does not eliminate the need to understand the subscription behavior of the resulting stream.
Handling Stream Errors
Streams can emit errors as well as data.
For example:
controller.addError(
Exception('Connection failed'),
);
Listen:
controller.stream.listen(
(data) {
print(data);
},
onError: (error) {
print('Error: $error');
},
);
You can also handle completion:
controller.stream.listen(
(data) {
print(data);
},
onError: (error) {
print(error);
},
onDone: () {
print('Stream closed');
},
);
A stream can therefore deliver:
Data Events
+
Error Events
+
Done Event
Closing StreamController
If you create a StreamController, you should normally close it when it is no longer needed.
await controller.close();
For a widget-owned controller:
@override
void dispose() {
controller.close();
super.dispose();
}
For long-lived services, close the controller when the service itself is disposed.
Leaving unnecessary stream controllers and subscriptions alive can lead to resource leaks or unexpected behavior.
Cancel StreamSubscription
If you manually subscribe:
late StreamSubscription<String>
subscription;
Then:
subscription =
service.stream.listen(
(event) {
// Handle event.
},
);
cancel it when appropriate:
@override
void dispose() {
subscription.cancel();
super.dispose();
}
This is especially important when listeners reference widgets, controllers, or other objects with limited lifetimes.
onListen and onCancel
StreamController can react when listeners subscribe or unsubscribe.
For example:
final controller =
StreamController<int>.broadcast(
onListen: () {
print('Listener connected');
},
onCancel: () {
print('Listener disconnected');
},
);
This can be useful when managing resources such as:
WebSocket connection
Sensor subscription
Location updates
Native event source
For example:
First Listener
↓
Start Resource
No Listeners
↓
Stop Resource
This avoids keeping expensive event producers active unnecessarily.
Sync vs Async StreamController
StreamController also supports a sync option.
For example:
StreamController<int>.broadcast(
sync: true,
);
However, synchronous controllers require careful understanding of Dart’s event ordering and reentrancy behavior.
For most application-level code, the default asynchronous behavior is easier and safer to reason about.
Do not enable synchronous delivery simply because it sounds faster.
Event Ordering
Streams preserve event ordering within the guarantees of their producer.
For example:
controller.add(1);
controller.add(2);
controller.add(3);
listeners observe the sequence in order:
1
2
3
For event-driven application logic, maintaining predictable ordering can be important.
Do Broadcast Listeners Receive Independent Copies?
Multiple broadcast listeners receive the same emitted event object.
For example:
controller.add(user);
Conceptually:
user
↙ ↘
Listener A Listener B
Dart does not automatically deep-copy the object for each listener.
If the object is mutable and one consumer changes it, that can create surprising behavior elsewhere.
Using immutable models is often safer in reactive architectures.
Single-Subscription Example with Repository
Consider a one-time sequential export process.
class ExportRepository {
Stream<double> exportData() async* {
for (int i = 1; i <= 10; i++) {
await performExportStep(i);
yield i / 10;
}
}
}
UI:
repository.exportData().listen(
(progress) {
print(
'${progress * 100}%',
);
},
);
This represents one export operation with one logical consumer.
Single-subscription behavior makes sense.
Broadcast Example with Repository
Now consider a service that distributes real-time application events.
class NotificationRepository {
final _controller =
StreamController<AppNotification>
.broadcast();
Stream<AppNotification>
get notifications =>
_controller.stream;
void receiveNotification(
AppNotification notification,
) {
_controller.add(notification);
}
Future<void> dispose() async {
await _controller.close();
}
}
Multiple components can listen:
Notification Stream
↓
┌─────┼─────────┐
↓ ↓ ↓
Badge Screen Logger
This is a natural broadcast use case.
Stream Architecture with GetX
If you use GetX, you can listen to a Dart stream and update reactive state.
For example:
class NotificationController
extends GetxController {
final NotificationRepository repository;
NotificationController(
this.repository,
);
final notifications =
<AppNotification>[].obs;
StreamSubscription<AppNotification>?
_subscription;
@override
void onInit() {
super.onInit();
_subscription =
repository.notifications.listen(
(notification) {
notifications.add(
notification,
);
},
);
}
@override
void onClose() {
_subscription?.cancel();
super.onClose();
}
}
The repository controls the event source.
The GetX controller converts those events into UI state.
Stream vs Rx Variables in GetX
Do not confuse:
Stream<T>
with:
Rx<T>
They solve related but different problems.
A Dart Stream represents asynchronous events over time.
GetX reactive variables represent observable application state.
A useful architecture can be:
WebSocket / Firebase / Database
↓
Stream
↓
GetX Controller
↓
Rx State
↓
Obx
↓
UI
You do not necessarily need to expose every low-level stream directly to widgets.
Which Stream Type Should a Repository Return?
Ask one important question:
What does this stream represent?
If it represents one sequential asynchronous operation:
Download
File Processing
Import
Export
Data Pipeline
single-subscription may be appropriate.
If it represents events observed independently by several parts of the application:
Connection Events
Notifications
Shared WebSocket Events
Global Application Events
broadcast behavior may make more sense.
Do not choose broadcast simply because it feels more flexible.
Common Mistake: Making Everything Broadcast
This is tempting:
StreamController<dynamic>.broadcast();
everywhere.
But doing so can hide ownership problems.
If an operation logically has one consumer, allowing unlimited listeners may make the architecture harder to understand.
Use broadcast when multiple listeners are genuinely part of the design.
Common Mistake: Expecting Event Replay
Consider:
controller.add('Logged In');
Then a screen subscribes later.
It may never receive:
Logged In
because it was not listening when the event occurred.
If the screen needs to know whether the user is currently logged in, that information should be stored as state.
Think:
Event:
User logged in
State:
User is logged in
These are not the same thing.
Common Mistake: Multiple listen() Calls
Consider:
final stream = service.getData();
stream.listen(handleA);
stream.listen(handleB);
If getData() returns a single-subscription stream, this fails.
Before converting it to broadcast, determine why two components need the same stream.
Sometimes the better solution is:
One subscription
↓
State Manager
↓
Multiple UI Consumers
rather than giving every widget a direct subscription.
Common Mistake: Forgetting to Cancel Subscriptions
For example:
service.stream.listen((event) {
setState(() {});
});
without storing and cancelling the subscription can allow callbacks to remain active longer than intended.
Instead:
late final StreamSubscription
subscription;
and later:
subscription.cancel();
when the owner is disposed.
Common Mistake: Forgetting to Close Controllers
If your class creates:
final controller =
StreamController<Event>.broadcast();
it also owns the responsibility for its lifecycle.
Provide:
Future<void> dispose() async {
await controller.close();
}
when appropriate.
Single-Subscription vs Broadcast: Real-World Examples
| Scenario | Typical Choice |
|---|---|
| File reading | Single-subscription |
| Data import pipeline | Single-subscription |
| Export progress | Single-subscription |
| Sequential processing | Single-subscription |
| Global app events | Broadcast |
| Shared WebSocket events | Broadcast |
| Multiple notification consumers | Broadcast |
| Connectivity events | Broadcast |
| Sensor events used by several components | Broadcast |
| One async generator operation | Single-subscription |
These are guidelines rather than universal rules. The exact data source and architecture still matter.
How to Choose the Correct Stream
Ask these questions.
Does the stream represent one operation?
For example:
Read this file
Process this download
Run this export
Consider a single-subscription stream.
Do several independent consumers need the same live events?
For example:
WebSocket message
Connectivity event
Global notification
Consider broadcast.
Must a late subscriber immediately know the current value?
Then a plain broadcast event stream alone may not be sufficient.
You probably need a state-retention strategy.
Is there only one UI consumer?
Do not convert the stream to broadcast unnecessarily.
Are duplicate subscriptions causing duplicate work?
Consider sharing the source or centralizing the subscription instead of creating more independent streams.
Production Architecture Example
A larger Flutter application might use streams like this:
Remote Sources
↙ ↓ ↘
WebSocket Firebase API
↓ ↓
Repository Layer
↓
Stream Services
↙ ↘
Single-Sub Broadcast
↓ ↓
Sequential Shared Events
Operations ↓
Controllers
↓
UI State
The stream type should match the behavior of each data source.
Best Practices for Dart Streams
When working with streams in Flutter and Dart:
- Use single-subscription streams for one-consumer asynchronous sequences.
- Use broadcast streams when multiple independent listeners genuinely need the same events.
- Do not assume broadcast streams replay old events.
- Separate application state from temporary events.
- Avoid converting every stream to broadcast.
- Store and cancel manual
StreamSubscriptionobjects. - Close
StreamControllerinstances when their owner is disposed. - Avoid creating expensive streams repeatedly inside
build(). - Keep low-level stream handling inside services and repositories when possible.
- Understand the source before using
asBroadcastStream(). - Handle data, errors, and stream completion.
- Use immutable event objects where multiple listeners share data.
- Do not confuse connectivity events with current connectivity state.
- Centralize shared subscriptions when duplicate subscriptions would create duplicate network or database work.
- Choose the stream type based on semantics, not convenience.
Final Comparison
The core difference can be summarized simply.
Single-Subscription Stream
Producer
↓
Stream
↓
One Listener
Best suited to a single asynchronous sequence.
Broadcast Stream
Producer
↓
Broadcast Stream
↙ ↓ ↘
Listener A Listener B Listener C
Best suited to shared live events.
The key difference is not simply:
One listener vs many listeners
You should also think about ownership, event lifetime, replay behavior, source lifecycle, and whether you are representing events or state.
Final Thoughts
Understanding Single-Subscription vs Broadcast Streams in Dart becomes especially important as Flutter applications move beyond basic API calls into real-time and event-driven functionality.
Use a single-subscription stream when the data represents one logical sequence:
Start Operation
↓
Event 1
↓
Event 2
↓
Event 3
↓
Complete
Use a broadcast stream when several independent consumers need live events:
Event Source
↓
Broadcast Stream
↙ ↓ ↘
UI Service Logger
Most importantly, remember that a broadcast stream is not automatically a state-management solution and does not automatically replay its previous event to new subscribers.
For production Flutter applications, a clean pattern is often:
External Data Source
↓
Repository / Service
↓
Dart Stream
↓
Controller / State Management
↓
UI
Choose single-subscription or broadcast behavior at the service or repository level based on what the data actually represents. Doing so keeps your asynchronous architecture predictable, prevents duplicate-listener errors, and makes real-time Flutter features much easier to maintain.
