FutureBuilder

Rebuilds with the latest AsyncSnapshot of future.

Import: package:fleury/fleury.dart, or package:fleury/fleury_core.dart in browser code.

Usage

// In your State: create the future once. Calling load() in build would
// start a new request on every rebuild.
late final Future<List<Item>> _items = load();

// In build:
FutureBuilder<List<Item>>(
  future: _items,
  builder: (context, snapshot) {
    if (snapshot.hasError) return Text('Failed: ${snapshot.error}');
    if (!snapshot.hasData) return const Text('Loading…');
    return ItemList(snapshot.data!);
  },
)

Details

Create the future once (in initState or a field) and pass the same instance — building it inline (future: fetch()) re-runs it on every rebuild, the classic FutureBuilder mistake. This widget re-subscribes only when the future identity changes, so a stable future is safe.

Constructors

`FutureBuilder()`

Parameter	Type	Default	Description
`future:`	`Future<T>?`	required	The asynchronous computation to observe. A null future stays disconnected.
`initialData:`	`T?`	—	Data exposed before `future` completes, or null when there is no seed value.
`builder:`	`AsyncWidgetBuilder<T>`	required	Builds the subtree from the latest connection state, data, or error.

Source

FutureBuilder is defined in packages/fleury/lib/src/widgets/async.dart.

Category: State & async · All widgets

Example · 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

Live · interactive

click & type to interact ⓘ how this demo runs