Loading data

Apps often need to wait for data, then show a result—or an error—when it arrives. Use FutureBuilder for one result and StreamBuilder for values that keep arriving.

The source produces…	Dart type	Build with
One eventual result	`Future<T>`	`FutureBuilder<T>`
Values over time	`Stream<T>`	`StreamBuilder<T>`
App-owned values changed by actions	A field or notifier	State management

The builders do not fetch, parse, cache, or save anything. They listen to an async source and pass its latest AsyncSnapshot<T> to your UI.

Load a result

Use FutureBuilder when a request produces one result. This example fetches and decodes a real photo from Lorem Picsum, then renders the loading, error, and success states. It uses two packages:

dart pub add http image

You write · editable

class _PhotoViewerState extends State<PhotoViewer> {
  late Future<img.Image> _photo = widget.loadPhoto();

  void _reload() => setState(() => _photo = widget.loadPhoto());

  @override
  Widget build(BuildContext context) => FutureBuilder<img.Image>(
    future: _photo,
    builder: (context, snapshot) {
      final loading = snapshot.connectionState == ConnectionState.waiting;
      if (snapshot.hasError && !loading) {
        return Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const Text('Could not load a photo.'),
            Button(text: 'Retry', onPressed: _reload),
          ],
        );
      }

      final photo = snapshot.data;
      if (photo == null) return const Text('Loading a photo from the web…');
      return Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text(loading ? 'Loading a new photo…' : 'Random landscape'),
          SizedBox(
            width: 48,
            height: 10,
            child: Image.decoded(
              photo,
              fit: ImageFit.cover,
              semanticLabel: 'Random landscape photo',
            ),
          ),
          Button(text: 'Load another', onPressed: loading ? null : _reload),
        ],
      );
    },
  );
}

import 'package:http/http.dart' as http;
import 'package:image/image.dart' as img;

Future<img.Image> fetchPhoto(int seed) async {
  final response = await http.get(
    Uri.parse('https://picsum.photos/seed/fleury-$seed/480/240.jpg'),
  );
  if (response.statusCode != 200) {
    throw StateError('Photo request failed (${response.statusCode})');
  }
  return img.decodeImage(response.bodyBytes) ??
      (throw const FormatException('Response was not an image'));
}

/// Mounts the photo viewer only after the reader asks for it, so opening a
/// page that embeds this demo sends no request to the photo service.
class _PhotoPreviewState extends State<_PhotoPreview> {
  var _seed = 0;
  var _started = false;

  @override
  Widget build(BuildContext context) => _started
      ? loading.PhotoViewer(loadPhoto: () => loading.fetchPhoto(++_seed))
      : Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const Text('Photos come from picsum.photos.'),
            Button(
              text: 'Load a photo',
              onPressed: () => setState(() => _started = true),
            ),
          ],
        );
}

Live preview

Load one result, then refresh it

Live · interactive

click & type to interact ⓘ how this demo runs

Press Load a photo to mount PhotoViewer. The preview waits for that press so that opening this page sends no request to Lorem Picsum; the viewer itself starts loading as soon as it builds.

Create the future once and keep it in state, as _photo does. A future created in build would start a new request on every rebuild. widget.loadPhoto is fetchPhoto with a new seed each time.

Check for an error before reading data, and keep side effects out of the builder: it can run more than once for the same snapshot.

On browser surfaces and terminals with inline-image support, Image renders true pixels. Other terminals fall back to character art from the same decoded image.

Refresh and retry

To load again, replace the future inside setState. The builder switches to the new future and ignores a late result from the old one; the old request itself is not cancelled.

Until the new future completes, the snapshot keeps the previous data and error, with connectionState set to waiting. That is what keeps the last photo on screen while Load another fetches the next one. It is also why the viewer shows an error only when it is not loading: after a failed attempt, Retry shows the loading state instead of repeating the old error, and the disabled button prevents a second request while one is running.

Handle every state

A snapshot’s connectionState says where the source is: none before there is one, waiting, active (streams only), then done. data and error carry the latest outcome. Most views need five states: nothing requested, loading, failed, empty, and ready. Choose a state to connect a matching Future:

You write · editable

(String, String) describe(AsyncSnapshot<List<String>> snapshot) {
  if (snapshot.connectionState == ConnectionState.none) {
    return ('DISCONNECTED', 'Choose a source to begin.');
  }
  if (snapshot.connectionState == ConnectionState.waiting) {
    return ('LOADING', 'Loading files…');
  }
  if (snapshot.hasError) return ('ERROR', 'Connection lost. Try again.');
  final files = snapshot.requireData;
  if (files.isEmpty) return ('EMPTY', 'The request completed with no files.');
  return ('READY', '${files.length} files loaded');
}

enum SnapshotPreview { disconnected, waiting, error, empty, success }

Future<List<String>>? futureFor(SnapshotPreview preview) => switch (preview) {
  SnapshotPreview.disconnected => null,
  SnapshotPreview.waiting => Completer<List<String>>().future,
  // Own the failure immediately, even if rendering is delayed or this preview
  // is replaced before a frame. FutureBuilder still receives the same error.
  SnapshotPreview.error => Future<List<String>>.error(
    StateError('Connection lost'),
  )..ignore(),
  SnapshotPreview.empty => Future<List<String>>.value(const <String>[]),
  SnapshotPreview.success => Future<List<String>>.value(const <String>[
    'alpha.log',
    'beta.log',
  ]),
};

class _SnapshotExplorerState extends State<SnapshotExplorer> {
  var _preview = SnapshotPreview.waiting;
  late Future<List<String>>? _future = futureFor(_preview);

  void _show(SnapshotPreview preview) => setState(() {
    _preview = preview;
    _future = futureFor(preview);
  });

  @override
  Widget build(BuildContext context) => Column(
    crossAxisAlignment: CrossAxisAlignment.start,
    children: [
      Select<SnapshotPreview>(
        value: _preview,
        semanticLabel: 'Snapshot state',
        onChanged: _show,
        options: const [
          SelectOption(
            value: SnapshotPreview.disconnected,
            label: 'Disconnected',
          ),
          SelectOption(value: SnapshotPreview.waiting, label: 'Loading'),
          SelectOption(value: SnapshotPreview.error, label: 'Error'),
          SelectOption(value: SnapshotPreview.empty, label: 'Empty'),
          SelectOption(value: SnapshotPreview.success, label: 'Success'),
        ],
      ),
      FutureBuilder<List<String>>(
        future: _future,
        builder: (context, snapshot) => AsyncStateCard(snapshot: snapshot),
      ),
    ],
  );
}

class AsyncStateCard extends StatelessWidget {
  const AsyncStateCard({super.key, required this.snapshot});

  final AsyncSnapshot<List<String>> snapshot;

  @override
  Widget build(BuildContext context) {
    final colors = Theme.of(context).colorScheme;
    final (label, detail) = describe(snapshot);
    final (symbol, accent) = switch (label) {
      'DISCONNECTED' => ('○', colors.foreground ?? Colors.white),
      'LOADING' => ('◌', colors.info),
      'ERROR' => ('×', colors.error),
      'EMPTY' => ('◇', colors.warning),
      _ => ('✓', colors.success),
    };
    final heading = CellStyle(foreground: accent, bold: true);
    return Container(
      border: BoxBorder(
        style: Theme.of(context).borderStyle,
        cellStyle: CellStyle(foreground: accent),
      ),
      padding: const EdgeInsets.symmetric(horizontal: 1),
      child: Column(
        mainAxisSize: MainAxisSize.min,
        crossAxisAlignment: CrossAxisAlignment.start,
        children: <Widget>[
          Text('$symbol $label', style: heading),
          Text(detail),
          if (label == 'READY')
            for (final file in snapshot.requireData) Text('  $file'),
        ],
      ),
    );
  }
}

Live preview

Choose the async result the builder should render

Live · interactive

click & type to interact ⓘ how this demo runs

describe reads the connection state before the error, for the same reason as the photo viewer, and AsyncStateCard draws its label and detail in a bordered card. Choose Error, then Loading: the card shows the new request, not the old failure.

Why the Error preview calls ..ignore()

A future that fails before anything listens reports an unhandled error, even if a builder subscribes a moment later. The preview creates its failed future ahead of the frame that renders it, so it marks the error as handled with ..ignore(). The builder still receives the error and renders the card. A real request is usually handed to a builder or awaited right away; if you start one early, handle its errors where you start it.

Keep heavy work off the UI isolate

A Fleury app renders, reads input, and handles signals on one Dart isolate. Waiting on I/O costs nothing, but synchronous CPU work — decoding a large image, parsing a big JSON document, sorting or diffing a large dataset — holds all of it until the work finishes: no frames, no keystrokes, and not even Ctrl+C, which arrives as input. Move that work to another isolate with Isolate.run and give the resulting future to a builder as usual:

import 'dart:isolate';
import 'dart:typed_data';

import 'package:image/image.dart' as img;

Future<img.Image> decodePhotoInBackground(Uint8List bytes) => Isolate.run(
  () =>
      img.decodeImage(bytes) ??
      (throw const FormatException('Response was not an image')),
);

To use it in the photo example, replace the return statement at the end of fetchPhoto, which calls img.decodeImage inline, with the background decode:

return decodePhotoInBackground(response.bodyBytes);

Isolate.run works in terminal apps and under fleury serve, where the app runs as a native process. A browser embed compiles to JavaScript, which has no isolates, so keep work there small — which is why the live photo example above decodes inline.

Stream updates

Use StreamBuilder when values keep arriving. This demo treats a tiny star-map transmission as five packets; each click emits a larger snapshot until the stream closes:

You write · editable

class _TransmissionViewState extends State<TransmissionView> {
  var _transmission = Transmission();
  late var _updates = _transmission.updates;

  void _restart() {
    _transmission.dispose();
    setState(() {
      _transmission = Transmission();
      _updates = _transmission.updates;
    });
  }

  @override
  void dispose() {
    _transmission.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) => StreamBuilder<List<String>>(
    key: ValueKey(_transmission),
    stream: _updates,
    initialData: const [],
    builder: (context, snapshot) {
      if (snapshot.hasError) {
        return Button(text: 'Signal lost. Restart', onPressed: _restart);
      }
      final lines = snapshot.requireData;
      final status = switch (snapshot.connectionState) {
        ConnectionState.none => 'OFFLINE',
        ConnectionState.waiting => 'CONNECTING',
        ConnectionState.active => 'LIVE',
        ConnectionState.done => 'COMPLETE',
      };
      final complete = snapshot.connectionState == ConnectionState.done;
      return Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text('$status · ${lines.length}/5 packets'),
          for (final line in lines) Text(line),
          Row(
            children: [
              Button(
                text: 'Next packet',
                onPressed: complete ? null : _transmission.receiveNext,
              ),
              const SizedBox(width: 1),
              Button(text: 'Restart', onPressed: _restart),
            ],
          ),
        ],
      );
    },
  );
}

class Transmission {
  static const chunks = <String>[
    '          *',
    '         / \\',
    '    *---*   *',
    '     \\   \\ /',
    '      *---*',
  ];

  final _controller = StreamController<List<String>>();
  var _received = 0;

  Stream<List<String>> get updates => _controller.stream;

  void receiveNext() {
    if (_received == chunks.length) return;
    _received++;
    _controller.add(chunks.take(_received).toList());
    if (_received == chunks.length) _controller.close();
  }

  void dispose() {
    if (!_controller.isClosed) _controller.close();
  }
}

Live preview

Receive the star map one packet at a time

Live · interactive

click & type to interact ⓘ how this demo runs

Keep the stream in state so rebuilds do not subscribe again. initialData supplies the data for the first frame, while the snapshot is still waiting; the first packet makes it active, and closing the stream makes it done.

Restart creates a new transmission and stream. Like FutureBuilder, a StreamBuilder that switches streams keeps showing the last data until the new one emits. Keying the builder by the transmission starts it over from initialData instead.

The builder cancels its subscription when it switches streams or leaves the tree. It does not close the source: whoever creates the StreamController closes it, as dispose and _restart do here. Dart’s stream guide covers transforming, listening to, and creating streams in more depth.

When builders stop being enough

Builders fit one subtree reflecting one async source. Move the work into an app-owned model or repository when widgets share it or you need caching, pagination, optimistic updates, coordinated sources, or offline policy. The UI can listen to that model with the tools in State management.

Loading data

Load a result

Refresh and retry

Handle every state

Keep heavy work off the UI isolate

Stream updates

When builders stop being enough

API reference