Widget that builds itself based on the latest snapshot of interaction with a Future.

Widget rebuilding is scheduled by the completion of the future, using State.setState, but is otherwise decoupled from the timing of the future. The builder callback is called at the discretion of the Flutter pipeline, and will thus receive a timing-dependent sub-sequence of the snapshots that represent the interaction with the future.

For a future that completes successfully with data, the builder may be called with either both or only the latter of the following snapshots:

  • new AsyncSnapshot<String>.withData(ConnectionState.waiting, null)
  • new AsyncSnapshot<String>.withData(ConnectionState.done, 'some data')

For a future completing with an error, the builder may be called with either both or only the latter of:

  • new AsyncSnapshot<String>.withData(ConnectionState.waiting, null)
  • new AsyncSnapshot<String>.withError(ConnectionState.done, 'some error')

The data and error fields of the snapshot change only as the connection state field transitions from waiting to done, and they will be retained when changing the FutureBuilder configuration to another future. If the old future has already completed successfully with data as above, changing configuration to a new future results in snapshot pairs of the form:

  • new AsyncSnapshot<String>.withData(ConnectionState.none, 'some data')
  • new AsyncSnapshot<String>.withData(ConnectionState.waiting, 'some data')

In general, the latter will be produced only when the new future is non-null. The former only when the old future is non-null.

A FutureBuilder behaves identically to a StreamBuilder configured with future?.asStream(), except that snapshots with ConnectionState.active may appear for the latter, depending on how the stream is implemented.

Sample code

This sample shows a FutureBuilder configuring a text label to show the state of an asynchronous calculation returning a string. Assume the _calculation field is set by pressing a button elsewhere in the UI.

new FutureBuilder<String>(
  future: _calculation, // a Future<String> or null
  builder: (BuildContext context, AsyncSnapshot<String> snapshot) {
    switch (snapshot.connectionState) {
      case ConnectionState.none: return new Text('Press button to start');
      case ConnectionState.waiting: return new Text('Awaiting result...');
      default:
        if (snapshot.hasError)
          return new Text('Error: ${snapshot.error}');
        else
          return new Text('Result: ${snapshot.data}');
    }
  },
)
Inheritance

Constructors

FutureBuilder({Key key, Future<T> future, @required AsyncWidgetBuilder<T> builder })
Creates a widget that builds itself based on the latest snapshot of interaction with a Future. [...]
const

Properties

builder AsyncWidgetBuilder<T>
The build strategy currently used by this builder. Cannot be null.
final
future Future<T>
The asynchronous computation to which this builder is currently connected, possibly null.
final
hashCode int
The hash code for this object. [...]
read-only, inherited
key Key
Controls how one widget replaces another widget in the tree. [...]
final, inherited
runtimeType Type
A representation of the runtime type of the object.
read-only, inherited

Methods

createState() State<FutureBuilder<T>>
Creates the mutable state for this widget at a given location in the tree. [...]
createElement() StatefulElement
Creates a StatefulElement to manage this widget's location in the tree. [...]
inherited
debugDescribeChildren() List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children. [...]
@protected, inherited
debugFillProperties(DiagnosticPropertiesBuilder description) → void
Add additional properties associated with the node. [...]
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed. [...]
inherited
toDiagnosticsNode({String name, DiagnosticsTreeStyle style }) DiagnosticsNode
Returns a debug representation of the object that is used by debugging tools and by toStringDeep. [...]
inherited
toString({DiagnosticLevel minLevel: DiagnosticLevel.debug }) String
Returns a string representation of this object.
inherited
toStringDeep({String prefixLineOne: '', String prefixOtherLines, DiagnosticLevel minLevel: DiagnosticLevel.debug }) String
Returns a string representation of this node and its descendants. [...]
inherited
toStringShallow({String joiner: ', ', DiagnosticLevel minLevel: DiagnosticLevel.debug }) String
Returns a one-line detailed description of the object. [...]
inherited
toStringShort() String
A short, textual description of this widget.
inherited

Operators

operator ==(other) bool
The equality operator. [...]
inherited