▾

FutureBuilder

FutureBuilder connects a screen to one async job and lets the widget tree render from the latest snapshot held in application state.

Use it when a screen needs request-and-response data: load products, fetch a profile, parse an imported file, save a document, or perform another one-shot operation where the app expects one success or one error. The widget declares the resource during component conversion. Reducers still own the state changes when the job completes.

Basic shape

use fission::prelude::*;

let products = FutureBuilder::new(
    ResourceKey::new("catalog.products"),
    PRODUCTS_JOB,
    view.state().product_request(),
    view.state().products.clone(),
    |_ctx, _view, snapshot| {
        ProductList {
            snapshot: snapshot.clone(),
        }
        .into()
    },
)
.deps(view.state().product_request())
.on_ok(with_reducer!(ctx, ProductsLoaded, on_products_loaded))
.on_err(with_reducer!(ctx, ProductsFailed, on_products_failed))
.into();

The important rule is that the snapshot is not hidden inside the widget. Store it in your app state. The success and error reducers update that state, and the next build renders the new snapshot.

Field table

Field	Type	Meaning	Notes / default behavior
key	ResourceKey	Stable identity for this job resource.	Keep it stable for the logical resource, not for a single frame.
job	JobRef<J>	The registered job to run.	The shell must register a handler for the job.
request	J::Request	Request payload passed to the job.	Cloneable request value.
snapshot	AsyncSnapshot<J::Ok, J::Err>	Current app-owned loading/data/error state.	Reducers update it after job callbacks.
on_ok	Option<ActionEnvelope>	Action dispatched when the job succeeds.	Use this to bind the success reducer.
on_err	Option<ActionEnvelope>	Action dispatched when the job fails.	Use this to bind the error reducer.
deps	Option<Vec<u8>>	Serialized dependency identity.	Changing deps restarts or preserves according to policy.
policy	ResourcePolicy	How resource changes are handled.	Defaults to RestartOnChange.
builder	AsyncWidgetBuilder<S, J::Ok, J::Err>	Pure closure that turns the current snapshot into UI.	Keep the closure small; delegate real UI to a named component that receives the snapshot.

Snapshot states

AsyncSnapshot has three pieces: a connection state, optional data, and optional error.

Use AsyncSnapshot::waiting() when a request starts. Use AsyncSnapshot::with_data(AsyncConnectionState::Done, value) when it succeeds. Use AsyncSnapshot::with_error(AsyncConnectionState::Done, error) when it fails. The helper methods data(), error(), has_data(), and has_error() make display widgets straightforward.

Production checklist

For FutureBuilder, review the fields that change behavior before treating the widget as finished: key, job, request, snapshot, on_ok, on_err. The goal is to make the product rule visible in state and actions, not hidden inside ad-hoc construction code.

•

Bind on_ok, on_err to explicit reducer actions and test that the reducer handles unavailable, duplicate, or invalid input safely.

•

Check the semantics tree for the user-facing label or role that makes this widget understandable without relying only on pixels.

•

Add at least one component or harness test that confirms the visible text, semantic role, action dispatch, and layout constraint that matter for this widget in context.

If a screen starts repeating the same FutureBuilder setup, extract a named component around this widget. That keeps the reference API small while making product code easier to read and safer for generated code to copy.

Spinner, CircularProgress, Skeleton, and Resources and async.