What is a FutureBuilder?

In Flutter, FutureBuilder is a widget that responds to changes in state or dependencies by building itself based on the most recent snapshot of a Future. With FutureBuilder, we can run asynchronous functions and update our UI based on the function’s output.

Syntax

FutureBuilder({
  Key? key,
  Future<T>? future,
  T? initialData,
  required AsyncWidgetBuilder<T> builder,
})

Note: The builder must not be null.

Parameters

  1. key: This property controls how another replaces one widget.
  2. future: This property represents the Future whose snapshot can be accessed by the builder function.
  3. initialData: This property represents the data that will be utilized to build the snapshots until a non-null Future has been completed.
  4. builder: This property represents the current build strategy.

Future states

The following are the states used to determine the future’s current state when using a FutureBuilder widget:

  1. ConnectionState.none: This indicates that initialData is being utilized as the defaultValue and that the future is null.

  2. ConnectionState.active: This indicates that although the future is not null, it has not yet been resolved.

  3. ConnectionState.waiting: This state indicates that the future is currently being resolved, and we’ll receive the outcome shortly.

  4. ConnectionState.done: This denotes the completion of the future.

Code

The following code shows how to use a FutureBuilder.

import 'package:flutter/material.dart';

void main() {
  runApp(const MaterialApp(home:  HomePage()));
}

class HomePage extends StatelessWidget {
  const HomePage({Key key}) : super(key: key);

  Future<String> getWriterName() {
    return Future.delayed(const Duration(seconds: 3), () => "Maria Elijah");
  }

  @override
  Widget build(BuildContext context) {
    return SafeArea(
        child: Scaffold(
      appBar: AppBar(
        automaticallyImplyLeading: false,
        backgroundColor: Colors.deepPurpleAccent,
        title: const Text('Flutter FutureBuilder'),
      ),
      body: SizedBox(
        width: double.infinity,
        child: Center(
          child: FutureBuilder(
            future: getWriterName(),
            initialData: "Code sample",
            builder: (BuildContext context, snapshot) {
              if (snapshot.connectionState == ConnectionState.waiting) {
                return const Center(
                  child: CircularProgressIndicator(
                    color: Colors.deepPurpleAccent,
                  ),
                );
              }
              if (snapshot.connectionState == ConnectionState.done) {
                if (snapshot.hasError) {
                  return Center(
                    child: Text(
                      'An ${snapshot.error} occurred',
                      style: const TextStyle(fontSize: 18, color: Colors.red),
                    ),
                  );
                } else if (snapshot.hasData) {
                  final data = snapshot.data;
                  return Center(
                    child: Text(
                      data,
                      style: const TextStyle(
                          fontSize: 20, fontWeight: FontWeight.bold),
                    ),
                  );
                }
              }

              return const Center(
                child: CircularProgressIndicator(),
              );
            },
          ),
        ),
      ),
    ));
  }
}
Example of a FutureBuilder widget

Explanation

Let’s explain the code above:

  • Lines 10–12: We defined the getWriterName function that returns a writer’s Future name after three seconds of delay. It simulates an asynchronous operation using the Future.delayed constructor.
  • Lines 15–22: We defined the build method of a widget that returns a SafeArea widget with a Scaffold as its child. The Scaffold contains an AppBar widget with a purple accent background color and a centered title displaying Flutter FutureBuilder.
  • Lines 23–55: We define the body section of the Scaffold widget; we use a SizedBox and Center widget to contain a FutureBuilder that monitors a Future. The FutureBuilder displays a CircularProgressIndicator while the Future is running and shows the result in a Text widget if it completes successfully. If the Future completes with an error, an error message is displayed in a Text widget.

Free Resources

Copyright ©2026 Educative, Inc. All rights reserved