# 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="" %} Watch this on Youtube: ### 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](/ui-building-blocks/widgets/default-properties.md). ### 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 --- # 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/future-builder.md?ask= ``` 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.