# 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](/ui-building-blocks/widgets/default-properties.md).

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digia.tech/ui-building-blocks/widgets/media-async-widgets/stream-builder.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.