FutureProvider

What Is FutureProvider?

FutureProvider is a type of provider in Riverpod that holds a Future . It's designed specifically for asynchronous operations like:

Making API calls (HTTP requests)
Reading from a database
Fetching data from local storage
Any operation that returns a Future

The key benefit of FutureProvider is that it handles the loading, data, and error states for you . Your UI can react to each state appropriately.

✅ When to Use FutureProvider

Use FutureProvider when you need to fetch data asynchronously and display it in your UI. It's perfect for API calls, database reads, and any operation that takes time to complete.

Defining a FutureProvider

Defining a FutureProvider is similar to a regular provider, but the creation function is marked as async and returns a Future .

lib/providers.dart – Defining a FutureProvider


        
         import
        
        
         'package:flutter_riverpod/flutter_riverpod.dart'
        
        ;
        
         // A FutureProvider that fetches a user from an API
        
        
         final
        
        userProvider = FutureProvider<User>((ref) async {
        
         // This function is called when the provider is first read
        
        
         final
        
        response = await http.get(Uri.parse(
        
         'https://api.example.com/user'
        
        ));
        
         return
        
        User.fromJson(response.body);
  });
        
         // A FutureProvider that fetches a list of posts
        
        
         final
        
        postsProvider = FutureProvider<List<Post>>((ref) async {
        
         final
        
        response = await http.get(Uri.parse(
        
         'https://api.example.com/posts'
        
        ));
        
         return
        
        postsFromJson(response.body);
  });

🔑 Key Points

The creation function is marked with async
It returns a Future of the desired type
The provider is read-only — you can't modify the data directly
To refresh the data, use ref.refresh(provider)

Reading a FutureProvider

When you watch a FutureProvider , you get an AsyncValue object that represents the current state of the asynchronous operation.

lib/main.dart – Using FutureProvider in a Widget


        
         import
        
        
         'package:flutter/material.dart'
        
        ;
        
         import
        
        
         'package:flutter_riverpod/flutter_riverpod.dart'
        
        ;
        
         import
        
        
         'providers.dart'
        
        ;
        
         class
        
        
         UserScreen
        
        
         extends
        
        ConsumerWidget {
    @override
    Widget
        
         build
        
        (BuildContext context, WidgetRef ref) {
        
         // 👀 Watch the user provider to get the AsyncValue
        
        
         final
        
        userAsync = ref.watch(userProvider);
        
         return
        
        Scaffold(
        appBar: AppBar(title: Text(
        
         'User Profile'
        
        )),
        body: Center(
          child: userAsync.when(
            loading: () => CircularProgressIndicator(),
            error: (error, stack) => Text(
        
         'Error: $error'
        
        ),
            data: (user) => Text(
        
         'Hello, ${user.name}!'
        
        ),
          ),
        ),
      );
    }
  }

Step-by-Step Explanation

1.

Define the Provider –


          userProvider

is a


          FutureProvider

that fetches a


          User

from an API. The


          async

function makes the HTTP request and returns the parsed user.

2.

Watch the Provider –


          ref.watch(userProvider)

returns an


          AsyncValue

that represents the current state of the future: loading, error, or data.

3.

Handle States – The


          .when()

method handles all three states:


          loading

shows a progress indicator,


          error

shows an error message, and


          data

displays the user's name.

4.

Automatic Caching – The result is cached after the first successful fetch. Subsequent reads return the cached data immediately without refetching.

The Three States of AsyncValue

AsyncValue is a sealed class that represents the three possible states of a Future :

⏳

Loading

The Future is currently executing. Show a loading indicator.

❌

Error

The Future completed with an error. Show an error message.

✅

Data

The Future completed successfully with data. Display the data.

Handling AsyncValue States


        
         final
        
        asyncValue = ref.watch(userProvider);
        
         // Method 1: Using .when() - most concise
        
        asyncValue.when(
    loading: () => CircularProgressIndicator(),
    error: (error, stack) => Text(
        
         'Error: $error'
        
        ),
    data: (user) => Text(user.name),
  );
        
         // Method 2: Using .maybeWhen() - with fallback
        
        asyncValue.maybeWhen(
    data: (user) => Text(user.name),
    orElse: () => Text(
        
         'Loading or error...'
        
        ),
  );
        
         // Method 3: Using conditionals
        
        
         if
        
        (asyncValue.isLoading) {
        
         return
        
        CircularProgressIndicator();
  }
        
         else
        
        
         if
        
        (asyncValue.hasError) {
        
         return
        
        Text(
        
         'Error: ${asyncValue.error}'
        
        );
  }
        
         else
        
        {
        
         return
        
        Text(asyncValue.value!.name);
  }

Refreshing FutureProvider Data

By default, FutureProvider caches the result after the first successful fetch. To refetch the data (for example, when the user pulls to refresh), use ref.refresh() .

lib/main.dart – Refresh Button


        
         class
        
        
         UserScreen
        
        
         extends
        
        ConsumerWidget {
    @override
    Widget
        
         build
        
        (BuildContext context, WidgetRef ref) {
        
         final
        
        userAsync = ref.watch(userProvider);
        
         return
        
        Scaffold(
        appBar: AppBar(
          title: Text(
        
         'User Profile'
        
        ),
          actions: [
            IconButton(
              icon: Icon(Icons.refresh),
              onPressed: () {
        
         // 🔄 Refresh the data
        
        ref.refresh(userProvider);
              },
            ),
          ],
        ),
        body: Center(
          child: userAsync.when(
            loading: () => CircularProgressIndicator(),
            error: (error, stack) => Column(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                Text(
        
         'Error: $error'
        
        ),
                ElevatedButton(
                  onPressed: () => ref.refresh(userProvider),
                  child: Text(
        
         'Retry'
        
        ),
                ),
              ],
            ),
            data: (user) => Text(
        
         'Hello, ${user.name}!'
        
        ),
          ),
        ),
      );
    }
  }

💡 Refresh vs. Watch

ref.watch() – Reads the provider and listens for changes
ref.refresh() – Invalidates the cached data and triggers a new fetch
ref.invalidate() – Marks the data as invalid without refetching (it will refetch on next watch)

Complete Example: Weather App

Here's a complete example of a weather app that uses FutureProvider to fetch weather data from an API. This demonstrates loading, error, and data states in a real-world scenario.

lib/weather.dart – Complete Weather App


        
         import
        
        
         'package:flutter/material.dart'
        
        ;
        
         import
        
        
         'package:flutter_riverpod/flutter_riverpod.dart'
        
        ;
        
         import
        
        
         'package:http/http.dart'
        
        
         as
        
        http;
        
         import
        
        
         'dart:convert'
        
        ;
        
         // 1. Define the data model
        
        
         class
        
        
         Weather
        
        {
        
         final
        
        String city;
        
         final
        
        double temperature;
        
         final
        
        String condition;

    Weather({
        
         required
        
        
         this
        
        .city,
        
         required
        
        
         this
        
        .temperature,
        
         required
        
        
         this
        
        .condition});

    factory Weather.fromJson(Map<String, dynamic> json) {
        
         return
        
        Weather(
        city: json[
        
         'name'
        
        ] ??
        
         'Unknown'
        
        ,
        temperature: (json[
        
         'main'
        
        ][
        
         'temp'
        
        ]
        
         as
        
        num).toDouble() -
        
         273.15
        
        ,
        condition: json[
        
         'weather'
        
        ][
        
         0
        
        ][
        
         'description'
        
        ] ??
        
         'Unknown'
        
        ,
      );
    }
  }
        
         // 2. Define the FutureProvider
        
        
         final
        
        weatherProvider = FutureProvider<Weather>((ref) async {
        
         // Fetch weather data from an API
        
        
         final
        
        response = await http.get(
      Uri.parse(
        
         'https://api.openweathermap.org/data/2.5/weather?q=London&appid=YOUR_API_KEY'
        
        ),
    );
        
         if
        
        (response.statusCode ==
        
         200
        
        ) {
        
         final
        
        data = json.decode(response.body);
        
         return
        
        Weather.fromJson(data);
    }
        
         else
        
        {
        
         throw
        
        Exception(
        
         'Failed to load weather: ${response.statusCode}'
        
        );
    }
  });
        
         // 3. The UI Widget
        
        
         class
        
        
         WeatherScreen
        
        
         extends
        
        ConsumerWidget {
    @override
    Widget
        
         build
        
        (BuildContext context, WidgetRef ref) {
        
         final
        
        weatherAsync = ref.watch(weatherProvider);
        
         return
        
        Scaffold(
        appBar: AppBar(title: Text(
        
         'Weather App'
        
        )),
        body: Padding(
          padding: EdgeInsets.all(
        
         16
        
        ),
          child: Center(
            child: weatherAsync.when(
              loading: () => Column(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  CircularProgressIndicator(),
                  SizedBox(height:
        
         16
        
        ),
                  Text(
        
         'Loading weather data...'
        
        ),
                ],
              ),
              error: (error, stack) => Column(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  Icon(Icons.error, size:
        
         64
        
        , color: Colors.red),
                  SizedBox(height:
        
         16
        
        ),
                  Text(
        
         'Error: $error'
        
        , textAlign: TextAlign.center),
                  SizedBox(height:
        
         16
        
        ),
                  ElevatedButton(
                    onPressed: () => ref.refresh(weatherProvider),
                    child: Text(
        
         'Retry'
        
        ),
                  ),
                ],
              ),
              data: (weather) => Card(
                child: Padding(
                  padding: EdgeInsets.all(
        
         24
        
        ),
                  child: Column(
                    mainAxisSize: MainAxisSize.min,
                    children: [
                      Text(
                        weather.city,
                        style: TextStyle(fontSize:
        
         24
        
        , fontWeight: FontWeight.bold),
                      ),
                      SizedBox(height:
        
         8
        
        ),
                      Text(
        
         '${weather.temperature.toStringAsFixed(1)}°C'
        
        ,
                        style: TextStyle(fontSize:
        
         48
        
        , fontWeight: FontWeight.w300),
                      ),
                      SizedBox(height:
        
         8
        
        ),
                      Text(weather.condition.toUpperCase()),
                      SizedBox(height:
        
         16
        
        ),
                      ElevatedButton.icon(
                        onPressed: () => ref.refresh(weatherProvider),
                        icon: Icon(Icons.refresh),
                        label: Text(
        
         'Refresh'
        
        ),
                      ),
                    ],
                  ),
                ),
              ),
            ),
          ),
        ),
      );
    }
  }

FutureProvider vs StateProvider

Handles asynchronous data
Built-in loading state
Built-in error state
Read-only (cannot modify data)
Data is cached after fetch
Perfect for API calls, database reads

StateProvider

Handles synchronous data
No loading state
No error state
Mutable (can modify data)
Data is not cached
Perfect for counters, toggles, form data

Common Mistakes

❌ Mistake 1: Not handling the loading state

If you don't handle the loading state, your UI might show an empty or incorrect state while the data is being fetched. Always handle all three states of AsyncValue .

✅ Correct: Always handle loading state

Use .when() or .maybeWhen() to handle loading, error, and data states explicitly.

❌ Mistake 2: Using ref.watch() inside event handlers

ref.watch() should only be used inside the build() method. For event handlers, use ref.refresh() or ref.invalidate() .

✅ Correct: Use ref.refresh() in event handlers

For refresh buttons or retry logic, use ref.refresh(provider) to trigger a new fetch.

❌ Mistake 3: Not handling errors gracefully

If an API call fails and you don't handle the error state, your app will show a red screen. Always handle the error state and provide a way for the user to retry.

✅ Correct: Show error messages and retry buttons

In the error state, show a friendly error message and a button to retry the operation.

FutureProvider

✅ When to Use FutureProvider

🔑 Key Points

💡 Refresh vs. Watch

FutureProvider

StateProvider

🎯 Key Takeaway