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.

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)

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.

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.

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