DEV Community: Emir Cihangir

What is BuildContext?

Emir Cihangir — Tue, 04 Aug 2026 09:07:58 +0000

If you are a Flutter developer, it is almost impossible not to encounter BuildContext. When Flutter builds a widget, it supplies a BuildContext to its build method. Whenever you try to access the theme of your Flutter app, you use Theme.of(context). But what exactly is context?

BuildContext is a handle to the location of a widget in the widget tree. You can think of it as the widget’s address within your app. It is not the widget or its state. That said, there are a few more things about BuildContext that are essential for our understanding.

Every BuildContext represents one specific location in the tree. The context passed to a build method belongs to the widget whose method is running, while the widgets returned by that method receive their own contexts.

A BuildContext can remain valid across many rebuilds. However, it becomes invalid when its associated element is unmounted. This is why Flutter warns us about using a context across asynchronous gaps: the widget may have been removed from the tree while the asynchronous operation was running. After an asynchronous gap, check context.mounted before using the context.

Let's further analyze BuildContext through a concrete example. As usual, create a Flutter project, navigate to lib/main.dart, and replace its contents with the following:

import 'package:flutter/material.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Theme(
        data: ThemeData(
          colorScheme: ColorScheme.fromSeed(seedColor: Colors.green),
          textTheme: TextTheme(bodyMedium: TextStyle(color: Colors.grey)),
        ),
        child: const MyHomePage(),
      ),
    );
  }
}

class MyHomePage extends StatelessWidget {
  const MyHomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.spaceEvenly,
          children: [
            FirstSection(),
            SecondSection(),
          ],
        ),
      ),
    );
  }
}

class FirstSection extends StatelessWidget {
  const FirstSection({super.key});

  @override
  Widget build(BuildContext context) {
    final theme = Theme.of(context);

    return Column(
      spacing: 8,
      children: [
        FilledButton(onPressed: () {}, child: Text('I am the first section button!')),
        Text('I am the first section body text!', style: theme.textTheme.bodyMedium),
      ],
    );
  }
}

class SecondSection extends StatelessWidget {
  const SecondSection({super.key});

  @override
  Widget build(BuildContext context) {
    final theme = Theme.of(context);

    return Column(
      spacing: 8,
      children: [
        FilledButton(onPressed: () {}, child: Text('I am the second section button!')),
        Text('I am the second section body text!', style: theme.textTheme.bodyMedium),
      ],
    );
  }
}

We have a fairly simple screen with a column that has two sections. This is what our widget tree looks like at this stage:

Notice how our home page is wrapped with a Theme widget.

Now let's take a look at the first line in the build method of both sections:

final theme = Theme.of(context);

In both sections, we tell Flutter to use context as the starting point and walk up the widget tree until it finds a Theme. In both cases, Theme.of(context) returns the ThemeData provided by the Theme widget just above MyHomePage. But let's make a change to make things interesting:

Wrap the FirstSection widget in a Theme widget and pass these values to it:

Theme(
    data: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.yellow),
        textTheme: TextTheme(bodyMedium: TextStyle(color: Colors.cyan)),
    ),
    child: FirstSection(),
),

This is what the widget tree should look like after the change:

Now perform a hot reload and see how the app changes. The first section now uses a different theme. This is because when Flutter starts from the FirstSection widget and walks upwards, the first Theme widget it sees is different from the one used by the SecondSection widget. In the SecondSection widget, Theme.of(context) sees the Theme that is right above the MyHomePage widget, and returns its ThemeData. However, in the FirstSection widget, it returns the ThemeData of the Theme widget that is right above itself. The BuildContext passed to Theme.of provides the starting location for each lookup, allowing it to select the nearest enclosing Theme.

Let's take a look at another example that might save you from future headaches. This example is very important and will help solidify your understanding of BuildContext. Replace the contents of lib/main.dart with the following:

import 'package:flutter/material.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Center(
          child: FilledButton(
            onPressed: () => ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text('Hi!'))),
            child: Text('Press me!'),
          ),
        ),
      ),
    );
  }
}

This is the widget tree:

Run the app and press the button. You will get an error that says: No ScaffoldMessenger widget found. It might seem odd at first. After all, the FilledButton is inside the Scaffold, so why is it not working?

The context passed to ScaffoldMessenger.of(context) belongs to the MyApp widget. Although the button appears inside the Scaffold, its callback captures MyApp's context, which is above the ScaffoldMessenger created by MaterialApp. Therefore, ScaffoldMessenger.of(context) cannot find a ScaffoldMessenger ancestor. To fix this, we need a new context from lower in the widget tree.

You can use the Builder widget like so:

Builder(
    builder: (context) {
        return FilledButton(
            onPressed: () => ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text('Hi!'))),
            child: Text('Press me!'),
        );
    },
)

Tip: If you are using VS Code, simply place the cursor on the FilledButton text, press the lightbulb icon, and press "Wrap with Builder".

Builder introduces a new BuildContext at its own position in the tree. The context passed to its callback belongs to the Builder widget and can be used by the FilledButton returned from that callback. With this change, our widget tree looks like this:

Perform a hot reload and press the button again. This time, Flutter successfully shows the snackbar. The context passed to ScaffoldMessenger.of now belongs to the Builder, which is below the ScaffoldMessenger created by MaterialApp. The lookup therefore finds the nearest enclosing ScaffoldMessenger, which displays the snackbar through its registered Scaffold.

BuildContext might seem confusing at first, but it all becomes easier when you realize it is just a widget's address within your app. When a context-based lookup fails, check where the context comes from and whether the widget you need encloses that location. If necessary, use Builder to obtain a context from lower in the tree, and always check if a context is still mounted before using it after an asynchronous gap.

Displaying async values in Flutter

Emir Cihangir — Wed, 29 Jul 2026 12:14:55 +0000

The build method in Flutter widgets is synchronous. That means it doesn’t like to wait for anything. But sometimes, we need to wait for a value to arrive in order to display it.

Let’s think of a simple weather app that displays only the temperature of a city. The app needs to make a request to the backend, get the temperature value, and finally display it. It will have to wait for a response from the backend, but as we discussed, the build method does not like to wait for anything. So how do we solve this issue?

Enter: FutureBuilder. FutureBuilder takes a value of type Future and displays widgets until it is resolved. In fact, we can specify which widgets to display not only while loading but also when an error occurs. Let’s see how we can use FutureBuilder in a simple app.

First, create an app in a directory of your choice:

flutter create future_builder --platforms=macos

You can choose whichever platform you want.

Open the project in your preferred IDE, and navigate to lib/main.dart. Replace the entire content of the file with the following:

import 'package:flutter/material.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(home: const MyHomePage());
  }
}

class MyHomePage extends StatelessWidget {
  const MyHomePage({super.key});

  Future<int> _getTemperature() async {
    await Future.delayed(Duration(seconds: 3)); // Dummy delay of three seconds.
    return 25;
  }

  Future<int> _getTemperatureError() async {
    await Future.delayed(Duration(seconds: 3));
    throw Exception('An error occurred while retrieving the temperature value.');
  }

  Future<int?> _getTemperatureEmpty() async {
    await Future.delayed(Duration(seconds: 3));
    return null;
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: FutureBuilder(
          future: _getTemperature(),
          builder: (context, snapshot) {
            if (snapshot.connectionState == ConnectionState.waiting) {
              return Column(
                mainAxisAlignment: MainAxisAlignment.center,
                spacing: 16,
                children: [
                  const CircularProgressIndicator(),
                  const Text('Loading temperature...'),
                ],
              );
            }

            if (snapshot.hasError) {
              return Text(snapshot.error.toString());
            }

            if (snapshot.hasData == false) {
              return const Text('No data');
            }

            final temperatureValue = snapshot.data!;
            return Text('Temperature: $temperatureValue');
          },
        ),
      ),
    );
  }
}

Finally, run the app by typing this on the terminal:

flutter run

The app will display a loading indicator for three seconds, then display a value. Let’s go over the code by first analyzing the FutureBuilder widget itself:

FutureBuilder(
  future: ...,
  builder: ...
)

FutureBuilder has two required parameters: future and builder. This might be one of the most straightforward and intuitive widgets in Flutter. The future parameter takes, you guessed it, a value of type Future, and the builder parameter takes a function with two parameters: context and snapshot. In the function we pass to builder, we specify which widgets to display for each state of snapshot. This is what we wrote:

(context, snapshot) {
  if (snapshot.connectionState == ConnectionState.waiting) {
    return Column(
      mainAxisAlignment: MainAxisAlignment.center,
      spacing: 16,
      children: [
        const CircularProgressIndicator(),
        const Text('Loading temperature...'),
      ],
    );
  }

  if (snapshot.hasError) {
    return Text(snapshot.error.toString());
  }

  if (snapshot.hasData == false) {
    return const Text('No data');
  }

  final temperatureValue = snapshot.data!;
  return Text('Temperature: $temperatureValue');
}

In the first if statement, we specified what needs to be displayed while the app waits for the value to arrive. In this case, a simple CircularProgressIndicator with a label.

In the second if statement, we defined what must be shown if the app encounters an error while waiting for the value. In this case, we simply chose to display the details of the error with a Text widget.

By the point the app makes it past the first two if statements, having snapshot.hasData return false means the future successfully resolved, but with a null value. In this case, we told the app to display ‘No data’.

Finally, if all goes well, we told the app to display the retrieved value with a Text widget. Now that we went over the builder function, let’s take a look at the functions that return Future:

Future<int> _getTemperature() async {
  await Future.delayed(Duration(seconds: 3)); // Dummy delay of three seconds.
  return 25;
}

Future<int> _getTemperatureError() async {
  await Future.delayed(Duration(seconds: 3));
  throw Exception('An error occurred while retrieving the temperature value.');
}

Future<int?> _getTemperatureEmpty() async {
  await Future.delayed(Duration(seconds: 3));
  return null;
}

All three of these functions first wait for three seconds, then behave in various ways to simulate potential outcomes of waiting for a value. The first one is the optimistic scenario: it successfully returns the value. The second throws an error, and the third one returns a null value. Let’s plug these into our FutureBuilder to see how they turn out:

FutureBuilder(
  future: _getTemperatureError(), // Change this
  builder: ...
)

Now perform a hot reload and observe what the app does. It displays a loading indicator for three seconds and then displays an error message, exactly as we defined in the builder function. Now let’s see what the app does when we pass the null-returning function to our FutureBuilder:

FutureBuilder(
  future: _getTemperatureEmpty(), // Change this
  builder: ...
)

After performing a hot reload, you will see that the app displays a loading indicator for three seconds, then displays the text ‘No data’.

This is the basic usage of FutureBuilder. It builds widgets based on the latest snapshot of its interaction with a Future, both before and after the future completes.