# Future Builder

The **Future Builder** widget lets you build UI based on the result of a **Future**—that is, any **asynchronous operation** like an API call, database query, file read, or long-running computation.\
It listens to the Future, and as its state changes (loading → completed → error), the Future Builder can show **different widgets for each state**.

{% embed url="<https://youtu.be/uXSEyrUQdUw?si=9CMQcMQ0seG8cVSp>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=uXSEyrUQdUw>

### Core Concepts

**a) Future-Driven UI**\
A **Future** represents a value that will be available later (success or error).\
The Future Builder:

* Takes a Future as input
* Listens to its state
* Rebuilds its child when the Future:
  * Is waiting
  * Completes with data
  * Completes with an error

So your UI is driven directly by async state, instead of manual flags.

**b) States and UI**\
Future Builder maps **states → UI**:

* Loading → show spinner, shimmer, or placeholder
* Error → show error message / retry
* Data → show final content

You decide what to show in each case; Future Builder switches automatically as the Future resolves.

**c) Actions**\
Actions around a Future Builder usually let you:

* Trigger the Future (e.g., call API)
* React to the result (update state, store data, navigate)
* Handle errors (show message, log, offer retry)

**d) Async Controller**\
The Async Controller prevents unnecessary refetching when the Future Builder rebuilds. It caches the result and only refetches when explicitly invalidated, improving performance for expensive async operations.

**e) Child of Future Builder**\
The **child** is typically a conditional or data-aware widget that:

* Receives the current **future state** and **data**
* Chooses what to render (loading, error, data UI)

{% hint style="info" %}
This keeps the Future Builder’s role focused on:

**Listening to the Future and exposing its state**,\
while the child takes care of **how the UI looks** for each state.
{% endhint %}

### **Properties**

| Property          | Description                                                                                                                                         |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Initial Data`    | The initial data to use while the Future is still resolving. This can be used to show cached or placeholder content before the real result arrives. |
| `AsyncController` | An Async Controller variable that manages async state and prevents unnecessary refetching. Use this to control when the Future should re-execute.   |
| `Data Source`     | Defines the **API endpoint / configuration** that the Future Builder will call to fetch data.                                                       |

### **Actions**

| Property     | Description                                                                                                                                                                                                                                                                                                                            |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `On Success` | Action triggered when the Future completes successfully. Receives an object with `futureState: 'completed'`, `futureValue` (the response data), and `response` (full API response details including statusCode, headers, etc.). Common uses: update UI state, store data, navigate to another screen, or trigger follow-up operations. |
| `On Error`   | Action triggered when the Future completes with an error. Receives an object with `futureState: 'error'`, `futureValue` (null), and `response` (error details including statusCode, headers, error message, etc.). Common uses: show an error notification, log the error, enable retry, or switch to fallback behavior.               |

### Child of Future Builder

| Slot    | Description                                                                                                                                                                                                                                                                                                                                                                                         |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `child` | The widget to build based on the state of the future. The child widget has access to the following variables: `futureState` (`'loading'`, `'error'`, `'completed'`), `futureValue` (the data or initial data), and `response` (API response details or error information). You can access these variables directly by name or with the Future Builder name prefix: `futureBuilderName.futureState`. |

#### Default Properties

The Future Builder widget supports all [default-properties](https://docs.digia.tech/ui-building-blocks/widgets/default-properties "mention").

### Use Cases

Use **Future Builder** when your UI depends on data that arrives later, for example:

* **Fetching Data from APIs**\
  Load user profile, products, or dashboard data and:
  * Show a loader while waiting
  * Show an error UI if the call fails
  * Show the actual content when data arrives
* **Local Async Operations**
  * Read from local/secure storage
  * Load cached config or initialization data
  * Run non-blocking computations
* **One-Time Async Flows**
  * Run setup logic when the screen opens
  * Wait for token refresh or session validation
  * Do pre-loading before showing the main screen