# 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.

{% embed url="<https://www.youtube.com/watch?v=0k-ImIalt60>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=0k-ImIalt60>

### 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](https://docs.digia.tech/ui-building-blocks/widgets/default-properties "mention").

### 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.