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.

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

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) 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 expression or controller used to trigger or control the execution of the Future (e.g., when to start, re-run, or refresh the async operation).
Type	Defines the type of Future to execute. Typically supports options like API (to call an endpoint) or Delay (for time-based simulation or waiting).
Duration (ms)	Used when Type is Delay. Specifies the delay duration in milliseconds before the future completes. Useful for timers, splash delays, or simulating loading.
Data Source	Used when Type is API. 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. Common uses: update UI state, store data, navigate to another screen, or trigger follow-up operations.
On Error	ction triggered when the Future completes with an error. 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. This child widget will have access to variables like futureState (loading, error, completed) and response.

Default Properties

The Future Builder widget supports all Default Properties.