DEV Community: Pedro Bueno

Simplifying State Management in Flutter with Command and Result

Pedro Bueno — Mon, 09 Feb 2026 19:38:44 +0000

About a year ago, the Flutter documentation was updated with new recommendations. Among its suggestions, such as the MVVM architecture I've commented on before, two patterns already known to programmers were indicated: Command and Result. In this article, we will see the advantage of using them, where they fit, and how to implement them in two flows of the same application.

As with every article I write, we will see a little bit of theory before going to the code, but today I will be very brief, I promise.

Knowing the patterns

Command

This pattern was born from the need to reuse code from the same function but without UI components knowing what they are doing. For a "send" button, it only triggers the execution of a command, without the need to execute the function passing any parameter, so the UI can be changed freely without affecting how the data is being executed.

We will then have a Command class, which will be the only one known by our buttons and UI components, and we will have the implementations, for example.

Right, so what?

In Flutter, this pattern is extended to already have information about the request state, indicating if it is being executed and if it finished with an error or success, so that we will have a single ListenableBuilder to react to the request, regardless of who executes it.

Result

The Result is simpler than it seems; I say this because many who start in the area feel that design patterns are something complex and end up imagining an even greater difficulty.

This pattern is simply a standardization of the return type of functions. Okay, it still sounds strange. Let's see an example:

Let's say we have a list of Contacts stored on a server and we want to make a call to it. As soon as we open our app, it searches and returns our list of contacts, so the expected result is a List<Contact>.

Oops, but this request can fail, like a lack of connection error, for example.

In this case, instead of throwing an error (throw Exception), we handle this error and display only a message "We are offline".

In this case, the one responsible for handling our error is the data access function (or class) itself, and whoever calls it (e.g., viewmodel) only needs to worry if the response is an error or success.

Preparing the environment

Starting

Considering you have already executed flutter create <your app>, first let's create a utils directory and add the following files to it: result.dart and command.dart. These two files are available in the flutter documentation (which I will add at the end of the article) and also other libraries like result_dart and command_it.

The official Flutter documentation created two Command classes, Command0 which receives no parameters and Command1 which receives parameters. Feel free to change the names to whatever is easier, for example, CommandWithParam for the second one. Here I will keep the original.

Changing our Result.dart

This is up to the programmer, but I like to add a .fold() function in the Result class, responsible for executing the functions received in case of success or failure, just to facilitate the ViewModel code and not need to write a Switch/Case every time.

Our Result class will be as follows:

sealed class Result<T> {
  const Result();

  /// Creates a successful [Result], completed with the specified [value].
  const factory Result.ok(T value) = Ok._;

  /// Creates an error [Result], completed with the specified [error].
  const factory Result.error(Exception error) = Error._;

  /// Applies one of two functions depending on the result type.
  ///
  /// If this is an [Ok], applies [onOk] to the value.
  /// If this is an [Error], applies [onError] to the error.
  R fold<R>({
    required R Function(T value) onOk,
    required R Function(Exception error) onError,
  }) {
    return switch (this) {
      Ok(value: final value) => onOk(value),
      Error(error: final error) => onError(error),
    };
  }
}

Creating the base structure

Just like every new Flutter app, let's remove the home_page.dart file, and create a presentation directory and inside it the home_list_page directory with the home_list_page.dart and home_list_viewmodel.dart files. In addition, inside /lib let's create the repositories folder and the to_do_repository.dart file inside it. Let's also create a models directory in /lib to store to_do.dart.

From the structure, you can see that my focus here is not to present a clean architecture since it is an example, but feel free to implement the architecture and structure that makes you most comfortable.

Our ToDo model will be as follows:

class ToDo {
  final String id;
  final String title;
  final bool isCompleted;

  ToDo({required this.id, required this.title, this.isCompleted = false});

  ToDo copyWith({String? id, String? title, bool? isCompleted}) {
    return ToDo(
      id: id ?? this.id,
      title: title ?? this.title,
      isCompleted: isCompleted ?? this.isCompleted,
    );
  }
}

Implementing the repository and Result

Our abstract repository class will be as follows:

abstract class ToDoRepository {
  Future<Result<List<ToDo>>> getToDos();
  Future<Result<void>> addToDo(ToDo toDo);
  Future<Result<void>> completeToDo(ToDo toDo);
  Future<Result<void>> deleteToDo(String id);
}

Here we already see our Result being used; it will be the base class for data return from our repository (and services if we need them in the future).

I will implement an in-memory repository, but feel free to implement it with Firestore, Isar, or Sqflite. It will be as follows:

class ToDoMemoryRepository implements ToDoRepository {
  // In-memory list of to-dos. In a real application, this would be replaced with
  // a database or API.
  final List<ToDo> _toDos = [ToDo(id: '1', title: 'Sample ToDo')];

  @override
  Future<Result<List<ToDo>>> getToDos() async {
    try {
      await Future.delayed(const Duration(seconds: 2));
      final List<ToDo> clonedList = List<ToDo>.from(_toDos);
      return Result.ok(clonedList);
    } catch (error) {
      return Result.error(Exception('Failed to get ToDos: $error'));
    }
  }

  @override
  Future<Result<void>> completeToDo(ToDo toDo) async {
    try {
      await Future.delayed(const Duration(seconds: 2));
      final index = _toDos.indexWhere((t) => t.id == toDo.id);
      if (index != -1) {
        _toDos[index] = toDo.copyWith(isCompleted: !toDo.isCompleted);
      }
      return const Result.ok(null);
    } catch (error) {
      return Result.error(Exception('Failed to complete ToDo: $error'));
    }
  }

  @override
  Future<Result<void>> addToDo(ToDo toDo) async {
    try {
      await Future.delayed(const Duration(seconds: 2));
      _toDos.add(toDo);
      return const Result.ok(null);
    } catch (error) {
      return Result.error(Exception('Failed to add ToDo: $error'));
    }
  }

  @override
  Future<Result<void>> deleteToDo(String id) async {
    try {
      await Future.delayed(const Duration(seconds: 2));
      _toDos.removeWhere((toDo) => toDo.id == id);
      return const Result.ok(null);
    } catch (error) {
      return Result.error(Exception('Failed to delete ToDo: $error'));
    }
  }
}

As said before, with Result, the one responsible for handling errors is the data access class. Here would be the moment to check the request status (if accessed via HTTP) and return a response according to the code, for example.

Implementing the list screen (Command without parameters)

Implementing the ViewModel

Our ViewModel will be simple, since the purpose is only to search the repository using the command. It will be the following code:

class HomeListViewmodel {
  final ToDoRepository _toDoRepository;

  // Command to load the list of to-dos.
  late final loadToDosCommand = Command0<List<ToDo>>(
    () => _toDoRepository.getToDos(),
  );

  // Load the to-dos when the view model is created.
  HomeListViewmodel(this._toDoRepository) {
    loadToDosCommand.execute();
  }
}

This way, as soon as our viewmodel is instantiated, it will execute our search.

Implementing our screen

To implement our screen we will assemble it in this order:

Instantiating our ViewModel
Scaffold to contain the screen and add Material configurations
The ListenableBuilder which will be the widget responsible for listening to our Command
The RefreshIndicator that will trigger our search when the user wants to update
The Builder that will read the state of our command and return a component that makes sense

Inside the builder, we will have the following logic:

If the command is still executing, we will display a CircularProgressIndicator (or any loading widget)

bool isLoading = viewModel.loadToDosCommand.running;
if (isLoading) {
  return const Center(child: CircularProgressIndicator());
}

Return the .fold of our Result to display a component according to its return, displaying EITHER a list OR an error message.

return viewModel.loadToDosCommand.result!.fold(
  onOk: (value) {
    final toDos = value;
    return ListView.builder(
      itemCount: toDos.length,
      itemBuilder: (context, index) {
        final toDo = toDos[index];
        return ListTile(
          title: Text(toDo.title),
          trailing: Checkbox(
            value: toDo.isCompleted,
            onChanged: (bool? newValue) {
              // Handle checkbox state change
            },
          ),
        );
      },
    );
  },
  onError: (error) {
    return Center(child: Text('Error: $error'));
  },
);

Thus, our list page:

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

  @override
  Widget build(BuildContext context) {
    // Create the view model for the home list page. In a real application, you
    // would typically use a dependency injection framework to provide the
    // repository and view model, but for this example, we'll just create them directly here.
    final viewModel = HomeListViewmodel(ToDoMemoryRepository());

    return Scaffold(
      appBar: AppBar(title: const Text('To-Do List')),
      body: ListenableBuilder(
        listenable: viewModel.loadToDosCommand,
        builder: (context, child) {
          return RefreshIndicator(
            child: Builder(
              builder: (context) {
                bool isLoading = viewModel.loadToDosCommand.running;
                if (isLoading) {
                  return const Center(child: CircularProgressIndicator());
                }

                return viewModel.loadToDosCommand.result!.fold(
                  onOk: (value) {
                    final toDos = value;
                    return ListView.builder(
                      itemCount: toDos.length,
                      itemBuilder: (context, index) {
                        final toDo = toDos[index];
                        return ListTile(
                          title: Text(toDo.title),
                          trailing: Checkbox(
                            value: toDo.isCompleted,
                            onChanged: (bool? newValue) {
                              // Handle checkbox state change
                            },
                          ),
                        );
                      },
                    );
                  },
                  onError: (error) {
                    return Center(child: Text('Error: $error'));
                  },
                );
              },
            ),
            onRefresh: () {
              return viewModel.loadToDosCommand.execute();
            },
          );
        },
      ),
    );
  }
}

If you prefer, you can add print or debugPrint to see the data flow in the terminal :)

Implementing the check flow in ToDo (Command with parameters)

Changing the ViewModel

Now that we can use Command without parameters, we will need to send something and we can do it without leaving the screen flow. As we already have the whole structure ready, we will only need to add the command to complete the ToDo in our ViewModel, following the logic of:

Trigger complete command
If success, update the ToDo list (execution of the first command)
If failure, return the error

For this, we will create a function inside the ViewModel and not a lambda as in the first one:

Future<Result<void>> _completeToDo(ToDo toDo) async {
    final result = await _toDoRepository.completeToDo(toDo);
    return result.fold(
      onOk: (_) {
        loadToDosCommand.execute();
        return const Result.ok(null);
      },
      onError: (error) {
        return Result.error(error);
      },
    );
  }

Thus, our ViewModel will look like this:

class HomeListViewmodel {
  final ToDoRepository _toDoRepository;

  // Command to load the list of to-dos.
  late final loadToDosCommand = Command0<List<ToDo>>(
    () => _toDoRepository.getToDos(),
  );

  // Command to mark a to-do as completed.
  late final completeToDoCommand = Command1<void, ToDo>(_completeToDo);

  // Load the to-dos when the view model is created.
  HomeListViewmodel(this._toDoRepository) {
    loadToDosCommand.execute();
  }

  Future<Result<void>> _completeToDo(ToDo toDo) async {
    final result = await _toDoRepository.completeToDo(toDo);
    return result.fold(
      onOk: (_) {
        loadToDosCommand.execute();
        // We return a successful result with no value, since the UI doesn't need
        // any data from this command, it just needs to know if it succeeded or failed.
        return const Result.ok(null);
      },
      onError: (error) {
        return Result.error(error);
      },
    );
  }
}

Implementing the list component

Let's create a widgets directory inside presentation to store our custom components and inside it, list_item.dart.

This component will be a ListenableBuilder that must receive the referring ToDo object and the command it must execute when marking as done. If it is loading, it should display a loading component to prevent the user from tapping multiple times while processing the request. In addition, if an error occurs, it should display a message via Snackbar.

Our component will be as follows:

class ListItem extends StatelessWidget {
  final ToDo toDo;
  final Command1<void, ToDo> onToggleCompleted;
  const ListItem({
    super.key,
    required this.toDo,
    required this.onToggleCompleted,
  });

  @override
  Widget build(BuildContext context) {
    return ListenableBuilder(
      listenable: onToggleCompleted,
      builder: (context, child) {
        final isRunning = onToggleCompleted.running;
        if (onToggleCompleted.result != null) {
          final result = onToggleCompleted.result!;
          result.fold(
            onOk: (_) {
              // Do nothing, the UI will update automatically when the command's
              // running state changes, which will cause the checkbox to show the
              // new completed state of the to-do.
            },
            onError: (error) {
              ScaffoldMessenger.of(
                context,
              ).showSnackBar(SnackBar(content: Text('Error: $error')));
            },
          );
        }
        return ListTile(
          title: Text(toDo.title),
          trailing: isRunning
              ? const CircularProgressIndicator()
              : Checkbox(
                  value: toDo.isCompleted,
                  onChanged: (bool? newValue) {
                    onToggleCompleted.execute(toDo);
                  },
                ),
        );
      },
    );
  }
}

Now just swap the ListTile of home_list_page.dart to test passing the completeToDoCommand as a parameter and see the behavior :)

Conclusion

I don't know if you noticed, but the loadToDosCommand command is being called in 3 different places: RefreshIndicator, ViewModel constructor, and _completeToDo function. But no one who calls it needs to know in depth who should call it, and yet they have access to its state and execution. It is precisely for this that we have this pattern.

Just as I said about the State pattern, neither Command nor Result are silver bullets (because there is no perfect pattern), but they are useful for development.

Analyze, implement, and see you next time :)

As with every article I write, we will see a little bit of theory before going to the code, but today I will be very brief, I promise.

Knowing the patterns

Command

file://%7B%22source%22%3A%22attachment%3A4b0ddc4e-5575-422d-9d2e-ce5bb9337e17%3Aimage.png%22%2C%22permissionRecord%22%3A%7B%22table%22%3A%22block%22%2C%22id%22%3A%2230289729-dbb1-803e-80ac-cac66eae6021%22%2C%22spaceId%22%3A%2235043d4e-7e79-4ea9-8984-f9260ce6e6e1%22%7D%7D

We will then have a Command class, which will be the only one known by our buttons and UI components, and we will have the implementations, for example.

file://%7B%22source%22%3A%22attachment%3A062ca9f1-cf4a-45d9-bed8-493ebb56fc99%3Aimage.png%22%2C%22permissionRecord%22%3A%7B%22table%22%3A%22block%22%2C%22id%22%3A%2230289729-dbb1-8051-93a9-f205a045e4f8%22%2C%22spaceId%22%3A%2235043d4e-7e79-4ea9-8984-f9260ce6e6e1%22%7D%7D

Right, so what?

Result

The Result is simpler than it seems; I say this because many who start in the area feel that design patterns are something complex and end up imagining an even greater difficulty.

This pattern is simply a standardization of the return type of functions. Okay, it still sounds strange. Let's see an example:

Oops, but this request can fail, like a lack of connection error, for example.

In this case, instead of throwing an error (throw Exception), we handle this error and display only a message "We are offline".

file://%7B%22source%22%3A%22attachment%3Afa1b9f2f-7cf4-4b02-b6aa-6044f8f3dc7c%3Aimage.png%22%2C%22permissionRecord%22%3A%7B%22table%22%3A%22block%22%2C%22id%22%3A%2230289729-dbb1-8075-92d4-f7600a88382b%22%2C%22spaceId%22%3A%2235043d4e-7e79-4ea9-8984-f9260ce6e6e1%22%7D%7D

Preparing the environment

Starting

Changing our Result.dart

Our Result class will be as follows:

sealed class Result<T> {
  const Result();

  /// Creates a successful [Result], completed with the specified [value].
  const factory Result.ok(T value) = Ok._;

  /// Creates an error [Result], completed with the specified [error].
  const factory Result.error(Exception error) = Error._;

  /// Applies one of two functions depending on the result type.
  ///
  /// If this is an [Ok], applies [onOk] to the value.
  /// If this is an [Error], applies [onError] to the error.
  R fold<R>({
    required R Function(T value) onOk,
    required R Function(Exception error) onError,
  }) {
    return switch (this) {
      Ok(value: final value) => onOk(value),
      Error(error: final error) => onError(error),
    };
  }
}

Creating the base structure

Our ToDo model will be as follows:

class ToDo {
  final String id;
  final String title;
  final bool isCompleted;

  ToDo({required this.id, required this.title, this.isCompleted = false});

  ToDo copyWith({String? id, String? title, bool? isCompleted}) {
    return ToDo(
      id: id ?? this.id,
      title: title ?? this.title,
      isCompleted: isCompleted ?? this.isCompleted,
    );
  }
}

Implementing the repository and Result

Our abstract repository class will be as follows:

abstract class ToDoRepository {
  Future<Result<List<ToDo>>> getToDos();
  Future<Result<void>> addToDo(ToDo toDo);
  Future<Result<void>> completeToDo(ToDo toDo);
  Future<Result<void>> deleteToDo(String id);
}

Here we already see our Result being used; it will be the base class for data return from our repository (and services if we need them in the future).

I will implement an in-memory repository, but feel free to implement it with Firestore, Isar, or Sqflite. It will be as follows:

class ToDoMemoryRepository implements ToDoRepository {
  // In-memory list of to-dos. In a real application, this would be replaced with
  // a database or API.
  final List<ToDo> _toDos = [ToDo(id: '1', title: 'Sample ToDo')];

  @override
  Future<Result<List<ToDo>>> getToDos() async {
    try {
      await Future.delayed(const Duration(seconds: 2));
      final List<ToDo> clonedList = List<ToDo>.from(_toDos);
      return Result.ok(clonedList);
    } catch (error) {
      return Result.error(Exception('Failed to get ToDos: $error'));
    }
  }

  @override
  Future<Result<void>> completeToDo(ToDo toDo) async {
    try {
      await Future.delayed(const Duration(seconds: 2));
      final index = _toDos.indexWhere((t) => t.id == toDo.id);
      if (index != -1) {
        _toDos[index] = toDo.copyWith(isCompleted: !toDo.isCompleted);
      }
      return const Result.ok(null);
    } catch (error) {
      return Result.error(Exception('Failed to complete ToDo: $error'));
    }
  }

  @override
  Future<Result<void>> addToDo(ToDo toDo) async {
    try {
      await Future.delayed(const Duration(seconds: 2));
      _toDos.add(toDo);
      return const Result.ok(null);
    } catch (error) {
      return Result.error(Exception('Failed to add ToDo: $error'));
    }
  }

  @override
  Future<Result<void>> deleteToDo(String id) async {
    try {
      await Future.delayed(const Duration(seconds: 2));
      _toDos.removeWhere((toDo) => toDo.id == id);
      return const Result.ok(null);
    } catch (error) {
      return Result.error(Exception('Failed to delete ToDo: $error'));
    }
  }
}

Implementing the list screen (Command without parameters)

Implementing the ViewModel

Our ViewModel will be simple, since the purpose is only to search the repository using the command. It will be the following code:

class HomeListViewmodel {
  final ToDoRepository _toDoRepository;

  // Command to load the list of to-dos.
  late final loadToDosCommand = Command0<List<ToDo>>(
    () => _toDoRepository.getToDos(),
  );

  // Load the to-dos when the view model is created.
  HomeListViewmodel(this._toDoRepository) {
    loadToDosCommand.execute();
  }
}

This way, as soon as our viewmodel is instantiated, it will execute our search.

Implementing our screen

To implement our screen we will assemble it in this order:

Instantiating our ViewModel
Scaffold to contain the screen and add Material configurations
The ListenableBuilder which will be the widget responsible for listening to our Command
The RefreshIndicator that will trigger our search when the user wants to update
The Builder that will read the state of our command and return a component that makes sense

Inside the builder, we will have the following logic:

If the command is still executing, we will display a CircularProgressIndicator (or any loading widget)

bool isLoading = viewModel.loadToDosCommand.running;
if (isLoading) {
  return const Center(child: CircularProgressIndicator());
}

Return the .fold of our Result to display a component according to its return, displaying EITHER a list OR an error message.

return viewModel.loadToDosCommand.result!.fold(
  onOk: (value) {
    final toDos = value;
    return ListView.builder(
      itemCount: toDos.length,
      itemBuilder: (context, index) {
        final toDo = toDos[index];
        return ListTile(
          title: Text(toDo.title),
          trailing: Checkbox(
            value: toDo.isCompleted,
            onChanged: (bool? newValue) {
              // Handle checkbox state change
            },
          ),
        );
      },
    );
  },
  onError: (error) {
    return Center(child: Text('Error: $error'));
  },
);

Thus, our list page:

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

  @override
  Widget build(BuildContext context) {
    // Create the view model for the home list page. In a real application, you
    // would typically use a dependency injection framework to provide the
    // repository and view model, but for this example, we'll just create them directly here.
    final viewModel = HomeListViewmodel(ToDoMemoryRepository());

    return Scaffold(
      appBar: AppBar(title: const Text('To-Do List')),
      body: ListenableBuilder(
        listenable: viewModel.loadToDosCommand,
        builder: (context, child) {
          return RefreshIndicator(
            child: Builder(
              builder: (context) {
                bool isLoading = viewModel.loadToDosCommand.running;
                if (isLoading) {
                  return const Center(child: CircularProgressIndicator());
                }

                return viewModel.loadToDosCommand.result!.fold(
                  onOk: (value) {
                    final toDos = value;
                    return ListView.builder(
                      itemCount: toDos.length,
                      itemBuilder: (context, index) {
                        final toDo = toDos[index];
                        return ListTile(
                          title: Text(toDo.title),
                          trailing: Checkbox(
                            value: toDo.isCompleted,
                            onChanged: (bool? newValue) {
                              // Handle checkbox state change
                            },
                          ),
                        );
                      },
                    );
                  },
                  onError: (error) {
                    return Center(child: Text('Error: $error'));
                  },
                );
              },
            ),
            onRefresh: () {
              return viewModel.loadToDosCommand.execute();
            },
          );
        },
      ),
    );
  }
}

If you prefer, you can add print or debugPrint to see the data flow in the terminal :)

Implementing the check flow in ToDo (Command with parameters)

Changing the ViewModel

Trigger complete command
If success, update the ToDo list (execution of the first command)
If failure, return the error

For this, we will create a function inside the ViewModel and not a lambda as in the first one:

Future<Result<void>> _completeToDo(ToDo toDo) async {
    final result = await _toDoRepository.completeToDo(toDo);
    return result.fold(
      onOk: (_) {
        loadToDosCommand.execute();
        return const Result.ok(null);
      },
      onError: (error) {
        return Result.error(error);
      },
    );
  }

Thus, our ViewModel will look like this:

class HomeListViewmodel {
  final ToDoRepository _toDoRepository;

  // Command to load the list of to-dos.
  late final loadToDosCommand = Command0<List<ToDo>>(
    () => _toDoRepository.getToDos(),
  );

  // Command to mark a to-do as completed.
  late final completeToDoCommand = Command1<void, ToDo>(_completeToDo);

  // Load the to-dos when the view model is created.
  HomeListViewmodel(this._toDoRepository) {
    loadToDosCommand.execute();
  }

  Future<Result<void>> _completeToDo(ToDo toDo) async {
    final result = await _toDoRepository.completeToDo(toDo);
    return result.fold(
      onOk: (_) {
        loadToDosCommand.execute();
        // We return a successful result with no value, since the UI doesn't need
        // any data from this command, it just needs to know if it succeeded or failed.
        return const Result.ok(null);
      },
      onError: (error) {
        return Result.error(error);
      },
    );
  }
}

Implementing the list component

Let's create a widgets directory inside presentation to store our custom components and inside it, list_item.dart.

Our component will be as follows:

class ListItem extends StatelessWidget {
  final ToDo toDo;
  final Command1<void, ToDo> onToggleCompleted;
  const ListItem({
    super.key,
    required this.toDo,
    required this.onToggleCompleted,
  });

  @override
  Widget build(BuildContext context) {
    return ListenableBuilder(
      listenable: onToggleCompleted,
      builder: (context, child) {
        final isRunning = onToggleCompleted.running;
        if (onToggleCompleted.result != null) {
          final result = onToggleCompleted.result!;
          result.fold(
            onOk: (_) {
              // Do nothing, the UI will update automatically when the command's
              // running state changes, which will cause the checkbox to show the
              // new completed state of the to-do.
            },
            onError: (error) {
              ScaffoldMessenger.of(
                context,
              ).showSnackBar(SnackBar(content: Text('Error: $error')));
            },
          );
        }
        return ListTile(
          title: Text(toDo.title),
          trailing: isRunning
              ? const CircularProgressIndicator()
              : Checkbox(
                  value: toDo.isCompleted,
                  onChanged: (bool? newValue) {
                    onToggleCompleted.execute(toDo);
                  },
                ),
        );
      },
    );
  }
}

Now just swap the ListTile of home_list_page.dart to test passing the completeToDoCommand as a parameter and see the behavior :)

Conclusion

Just as I said about the State pattern, neither Command nor Result are silver bullets (because there is no perfect pattern), but they are useful for development.

Analyze, implement, and see you next time :)

Code

https://github.com/arcbueno/CommandResultArticle

Source

Flutter's command documentation
Flutter's result documentation

Understanding and applying the State pattern in Flutter (Part 2)

Pedro Bueno — Sat, 13 Sep 2025 19:07:05 +0000

This article is a continuation of Part 1 in which I approach the problem in a more theoretical way. Here we will implement the State pattern in a simple way, using good practices. The focus will be on implementing a contact list screen (example from part 1).

Content

Remembering...
Structuring
- Models
- Repositories
Our state
- Declaring
- Defining the states of our screen
- when()
Our ViewModel
- Instantiating the ValueNotifier
- Constructor and dependencies
- Data access functions
Our screen
- LoadedPageWidget
- LoadingWidget
- ContactsErrorWidget
- Our main page
Conclusion

Remembering...

What is State?

The State pattern is a useful tool for developing systems, for managing what the system should react to and how it might behave. Its use makes it easier to maintain and control what the system should display or react to.

Because of its usefulness, it is also used by default by BLoC, one of the most widely used libraries in Flutter and a reference in state management.

What are we going to implement?

As discussed in part 1, we're going to use the example of a contact list screen, where it should display the user's customized name, the list of contacts, but also display different components depending on the current state (loading, error or loaded).

The logic is based on a finite state machine, where there is an initializer (initial state) that starts the flow of states.

Structuring

As the focus isn't on architecture, let's be straightforward and create 2 simple folders: one for repositories and another for the folder where we'll keep our UI, ViewModel and state. The suffixes of the files and the logic class (ViewModel/Controller/Store) are up to the programmer. The focus here is on the state. As a reactivity tool, I'm going to use ValueNotifier because it's easy and it's already included in the Flutter, but feel free to use MobX, GetX, ChangeNotifier or any other library.

The structure of our project will be as follows:

📂 lib
├─ 📄 main.dart - The central file of the project
├─ 📂 pages
│ └─ 📂 contacts_list
│ ├─ 📄 contacts_list.viewmodel.dart - ViewModel of our screen
│ ├─ 📄 contacts_list.page.dart - Central page of our UI
│ ├─ 📄 contacts_list.state.dart - Our state file
│ └─ 📂 widgets - Directory for storing components used on our page
│ ├─ 📂 repositories
│ ├─ 📄 contacts.repository.dart - Repository for accessing contact data
│ └─ 📄 user.repository.dart - Repository for accessing user data
│ └─ 📂 models
├─ 📄 contact.dart - Contact model
└─ 📄 user.dart - User model

Models

These will be simple, just for displaying information

// user.dart
class User {
  final int id;
  final String name;
  final String email;

  User({required this.id, required this.name, required this.email});
}

// contact.dart
class Contact {
  final int id;
  final String name;
  final String email;
  final String phoneNumber;

  Contact({
    required this.id,
    required this.name,
    required this.email,
    required this.phoneNumber,
  });
}

Repositories

The repositories will be simple, with just an access function that should return that data, no registration, just mocked up data.

// contacts.repository.dart
import 'package:state_pattern/models/contact.dart';

class ContactsRepository {
  Future<List<Contact>> fetchContacts() async {
    // Simulate network delay
    await Future.delayed(Duration(seconds: 2));

    // Return a list of dummy contacts
    return [
      Contact(
        id: 1,
        name: 'Alice',
        email: 'alice@example.com',
        phoneNumber: '123-456-7890',
      ),
      Contact(
        id: 2,
        name: 'Bob',
        email: 'bob@example.com',
        phoneNumber: '987-654-3210',
      ),
      Contact(
        id: 3,
        name: 'Charlie',
        email: 'charlie@example.com',
        phoneNumber: '555-555-5555',
      ),
    ];
  }
}

// user.repository.dart
import 'package:state_pattern/models/user.dart';

class UserRepository {
  Future<User> fetchUser() async {
    // Simulate network delay
    await Future.delayed(Duration(seconds: 2));
    // Return a dummy user
    return User(id: 1, name: "John Doe", email: "john.doe@example.com");
  } 
}

I particularly like the Result pattern for returning data from data classes, but that's for another time

Our state

Declaring

Our state will be an empty class, declared with the word "sealed".

Sealed classes are implicitly abstract classes and are also limited to being extended and allow us to create switch/cases in an "exhaustive" way, similar to an enum. Let's get a better understanding of using switch/case.

// contacts_list.state.dart
sealed class ContactsListState {}

Defining the states of our screen

As defined by our diagram, we'll have 4 classes that will extend ContactsListState and what they would have in each one

// contacts_list.state.dart
class InitialState extends ContactsListState {}

class LoadingState extends ContactsListState {}

class ErrorState extends ContactsListState {
  final String message;
  ErrorState(this.message);
}

class LoadedState extends ContactsListState {
  final List<Contact> contactList;
  final User user;
  LoadedState({required this.contactList, required this.user});
}

This way, we've defined a base type for our states and we're sure that it's a ContactsListState.

Regarding the state, I have 2 comments

I recommend defining prefixes or suffixes in the context-related names (e.g. ContactListLoadingState, ContactListErrorState), I haven't used them now because I only have one class for each state.
InitialState is not mandatory, I created it to define the beginning of our screen and for teaching purposes. If you prefer, you can remove it and start with the state you prefer.

when()

A very common function to use in classes of this type in BLoC because of its practicality is the when() function, which performs an action from each defined class. It will be implemented in the base state.

So, we have our final file

// contacts_list.state.dart
import 'package:state_pattern/models/contact.dart';
import 'package:state_pattern/models/user.dart';

sealed class ContactsListState {

  T when<T>({
    required T Function() initial,
    required T Function() loading,
    required T Function(String message) error,
    required T Function(List<Contact> contactList, User user) loaded,
  }) {
    switch (this) {
      case InitialState():
        return initial();
      case LoadingState():
        return loading();
      case ErrorState(:final message):
        return error(message);
      case LoadedState(:final contactList, :final user):
        return loaded(contactList, user);
    }
  }

}

class InitialState extends ContactsListState {}

class LoadingState extends ContactsListState {}

class ErrorState extends ContactsListState {
  final String message;
  ErrorState(this.message);
}

class LoadedState extends ContactsListState {
  final List<Contact> contactList;
  final User user;
  LoadedState({required this.contactList, required this.user});
}

Our ViewModel

Instantiating the ValueNotifier

As I said earlier, I chose to use ValueNotifier so as not to necessarily use any library. In fact, it's what I end up preferring to use in my day-to-day work, but if you prefer to use another class to define reactivity, that's up to you. :)

As mentioned before, its initial state will be InitialState and we can create it as final, since its base instance won't be changed, only the value inside ValueNotifier.

final ValueNotifier<ContactsListState> stateNotifier = ValueNotifier(InitialState());

Constructor and dependencies

It's a bit difficult not to talk about dependencies, but we're going to declare them and receive them through the constructor in a way that allows Dependency Injection in the future, if you want to use it as a base.

  final ContactsRepository _contactsRepository;
  final UserRepository _userRepository;

  ContactsListViewModel({
    required ContactsRepository contactsRepository,
    required UserRepository userRepository,
  }) : _contactsRepository = contactsRepository,
       _userRepository = userRepository;

Data access functions

Before outputting our state, we also need the data first, so we'll access it using the getAllData() function

Future<void> getAllData() async {
    // Emitting loading state   
  stateNotifier.value = LoadingState();

  try {
    final user = await _userRepository.fetchUser();
    final contacts = await _contactsRepository.fetchContacts();

        // Emitting LoadedState, as we have all the data needed
    stateNotifier.value = LoadedState(user: user, contactList: contacts);
  } catch (error) {
    stateNotifier.value = ErrorState(error.toString());
  }
}

From there we have our simple ViewModel ready, so let's move on to the screen.

Our screen

If we're going to display a specific widget for each state, then we'll implement a separate component each time.

As our state is being managed by the pattern in question, I'm going to focus on using StatelessWidgets, but that doesn't mean we shouldn't use StatefulWidgets

LoadedPageWidget

Our LoadedPageWidget will only be displayed when we have access to the user's name and contact list (LoadedState), so our component will receive these two pieces of information as parameters. It should display the user's name with a greeting, a list of users and have a button to update the information.

Let's create the list item

// contact_item_widget.dart
class ContactItemWidget extends StatelessWidget {
  final String name;
  final String email;
  const ContactItemWidget({super.key, required this.name, required this.email});

  @override
  Widget build(BuildContext context) {
    return ListTile(
      title: Text(name),
      subtitle: Text(email),
      trailing: Row(
        mainAxisSize: MainAxisSize.min,
        children: [
          IconButton(
            onPressed: () => print('Open whatsapp'),
            icon: const Icon(Icons.edit),
          ),
          IconButton(
            onPressed: () => print('Open call number'),
            icon: const Icon(Icons.phone),
          ),
        ],
      ),
    );
  }
}

Then our widget will look like this

// loaded_widget.dart
class LoadedWidget extends StatelessWidget {
  final User user;
  final List<Contact> contacts;
  const LoadedWidget({super.key, required this.user, required this.contacts});

  @override
  Widget build(BuildContext context) {
    return Card(
      child: Padding(
        padding: const EdgeInsets.all(8.0),
        child: Column(
          children: [
            Text(
              'Hello, ${user.name}, here are your contacts:',
              style: Theme.of(context).textTheme.titleLarge,
            ),
            Padding(
              padding: const EdgeInsets.symmetric(horizontal: 8.0),
              child: Row(
                mainAxisAlignment: MainAxisAlignment.end,
                children: [
                  IconButton(
                    onPressed: () => onRefresh(),
                    icon: Icon(Icons.refresh),
                  ),
                ],
              ),
            ),
            Expanded(
              child: ListView.separated(
                separatorBuilder: (context, index) => Divider(
                  indent: 16,
                  endIndent: 16,
                  color: Colors.grey.shade300,
                ),
                itemCount: contacts.length,
                itemBuilder: (context, index) {
                  final contact = contacts[index];
                  return ContactItemWidget(
                    name: contact.name,
                    email: contact.email,
                  );
                },
              ),
            ),
          ],
        ),
      ),
    );
  }
}

And that will be the goal:

LoadingWidget

As we discussed in the last article, we're going to make a skeleton, i.e. a component that acts as a shadow of what will be displayed. To speed things up, we're going to use the Skeletonizer package just to be quicker at the moment, but Flutter already has native solutions. Let's take advantage and reuse our contact item list component

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

  @override
  Widget build(BuildContext context) {
    return Skeletonizer(
      enabled: true,
      child: Column(
        children: [
          Text(
            'This is a text placeholder',
            style: Theme.of(context).textTheme.titleLarge,
            textAlign: TextAlign.center,
          ),
          Padding(
            padding: const EdgeInsets.symmetric(horizontal: 8.0),
            child: Row(
              mainAxisAlignment: MainAxisAlignment.end,
              children: [
                IconButton(onPressed: () {}, icon: Icon(Icons.refresh)),
              ],
            ),
          ),
          Expanded(
            child: ListView.separated(
              separatorBuilder: (context, index) => Divider(
                indent: 16,
                endIndent: 16,
                color: Colors.grey.shade300,
              ),
              itemCount: 7,
              itemBuilder: (context, index) {
                final contact = Contact(
                  id: index,
                  name: 'Loading...',
                  email: 'Loading...',
                  phoneNumber: 'Loading...',
                );
                return ContactItemWidget(
                  name: contact.name,
                  email: contact.email,
                );
              },
            ),
          ),
        ],
      ),
    );
  }
}

And that's our goal:

ContactsErrorWidget

Our error component will be simple: an icon, a title and a message.

// contacts_error_widget
class ContactsErrorWidget extends StatelessWidget {
  final String message;

  const ContactsErrorWidget({super.key, required this.message});

  @override
  Widget build(BuildContext context) {
    return Center(
      child: Column(
        mainAxisAlignment: MainAxisAlignment.center,
        mainAxisSize: MainAxisSize.min,
        children: [
          Icon(
            Icons.sentiment_dissatisfied,
            color: Colors.red.shade700,
            size: 128,
          ),
          SizedBox(height: 16),
          Text(
            'Oh no! An error occurred:',
            style: Theme.of(context).textTheme.headlineSmall?.copyWith(
              color: Colors.red.shade700,
              fontWeight: FontWeight.bold,
            ),
            textAlign: TextAlign.center,
          ),
          SizedBox(height: 8),
          Text(
            message,
            style: Theme.of(
              context,
            ).textTheme.bodyLarge?.copyWith(color: Colors.red.shade400),
            textAlign: TextAlign.center,
          ),
        ],
      ),
    );
  }
}

This is our result

Our main page

So after making our 3 main components, let's just put them together on our main screen, using the ValueListenableBuilder (since we're using ValueNotifier for our reactivity) to display them according to what we need.

So here's what we're going to do: instantiate the ViewModel, fire the data access function and return the widget from our screen.

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

  @override
  Widget build(BuildContext context) {
    // Creating an instance of the ViewModel
    final viewModel = ContactsListViewModel(
      contactsRepository: ContactsRepository(),
      userRepository: UserRepository(),
    );

    // Start fetching data when the widget is built
    viewModel.getAllData();

    return Scaffold(
      appBar: AppBar(title: const Text('Contacts List')),
      body: ValueListenableBuilder(
        valueListenable: viewModel.stateNotifier,
        builder: (context, state, child) {
          return state.when(
            initial: () => LoadingWidget(),
            loading: () => LoadingWidget(),
            error: (errorMessage) => ContactsErrorWidget(message: errorMessage),
            loaded: (contacts, user) =>
                LoadedWidget(user: user, contacts: contacts),
          );
        },
      ),
    );
  }
}

"Ah, Pedro, but what about the InitialState?" It has its uses, but the main reason it exists is just to start the state management flow, so much so that it is replaced at the beginning of getAllData() and never used again. But you can create a specific widget for it if you like.

If you want to test how the error display works, just add a throw Exception("Example error") to see how the UI reacts.

Conclusion

So that's it, we have a working feature using the State pattern.

The example we used is simplified into 3 base states, but we should also model and understand that these states should only reflect our need, and not make our need mold itself to each one. Like a form, for example, it can have different states, each with its own reaction, such as empty, filled in, under review, loading...

This pattern, like everything else in programming, is not something that will always work, but it is important to have the knowledge to know where and when to apply it and it has been very useful in developing my features.

I hope this article has been useful to you, thank you :)

The code is available on my Github: https://github.com/arcbueno/StatePatternFlutter

Understanding and applying the State pattern in Flutter (Part 1)

Pedro Bueno — Mon, 01 Sep 2025 00:31:39 +0000

When developing frontend applications, we often come across the idea of states: whether it's an application, a screen or a specific flow. This adds a lot of information and reactivity, and we end up calling this process "state management", even though we don't fully understand what a state is or how it affects our application. In this article, we'll look at a problem, a solution and its implementation, deepening our understanding of state management.

Topics

Problem
- Let's start with an example
- But what does this affect?
Solution
- What is the State pattern?
- Drawing
Implementation

Problem

Let's start with an example

"In the contact list, we're separating our business logic from the UI, isn't that cool?!"

-Yes, but let's think about it: will the screen's content change depending on some value? If so, what values would those be?

"From that contact list and the user's customized name that are loaded afterwards, but that's it"

-I see, but would there be any loading or error components displayed?

"Yes, yes. If it's loading, we display a skeleton. If there's an error, we display an error component with the error message and the try again button"

...

And so, a screen needs to listen to a few variables: the contact list, the user's customized name, perhaps a boolean indicating whether it's loading and an error message (which would be nullable). Quite a lot for a simple screen, isn't it? This scenario is more common than it sounds.

If a state is a value that affects the flow of a system, our contact screen - the system in question - has more states than necessary. In the end, if everything is a state, then nothing is a state. The concept loses its relevance and only adds complexity to the code.

But what does this affect?

In this scenario, the screen would have to have several reactive components (ValueListenableBuilder, ListenableBuilder, BlocBuilder, Obx... take your pick), but we can still imagine what something inevitable would look like: an AppBar that displays the user's custom name, a skeleton that may or may not be displayed, a list and an error component. On a mobile device.

Now understand that this behavior can be repeated in a similar way on other screens, also considering that the flutter reloads the current screen during navigation.

We end up dealing with 2 main problems:

Too many things being rendered: Flutter has improved its performance a lot, but the more things being rendered in parallel, the more hardware it will take
Code reading and debugging: there is no single way to update the screen, any change to these variables will trigger rebuilds asynchronously, one function being executed can affect the work of another function.

Who can help us?

Solution

The way forward became clearer, but when I came across these problems during development, the use of the State Design Pattern became obvious. It is so recommended that BLoC - a reference library in the Flutter environment - already uses it by default.

What is the State pattern?

This format is based on something that, if you've studied Computer Science, you've probably heard of: finite state machine, which although it sounds complex is like a door that only has the state of open or closed and that's it, or Super Mario: standing still, walking or jumping.

Just as object-oriented programming is a simplification of today's world, everything in a way is also a finite state machine. And so is your screen.

This standard will simplify and create classes that represent these states: if loading, loading state, if error, error state, if data loaded....? Loaded state. Each with the information that is relevant to each state, not least because there is no need for a loaded state to have an error message that it won't use.

Drawing

So let's make a quick diagram to understand the flow of our screen: we'll have 3 main states:

LoadingState → To display the skeleton
ErrorState → To display the error message and the try again button
LoadedState → To display the list and the user's name

In particular, I would recommend using a context prefix (e.g. ContactsLoadingState) so as not to confuse if other screens also use the pattern, but as we only have one context here I'll keep it that way.

In addition, I also suggest adding an InitialState, which would be the kick that starts the flow so that we can understand the transitions.

Regarding flows, we can follow a few rules:

LoadingState can trigger LoadedState OR ErrorState, only one or the other.
LoadedState can only trigger LoadingState (no error display on an already loaded screen).
ErrorState can only trigger LoadingState (if the user tries again)
InitialState can only trigger LoadingState (first component displayed is the skeleton)

From this we have this flow:

Implementation

And it's from this flow that we'll implement a solution on this contact screen on the next article.

See you later!

Part 2 is already available!

Sources:

https://refactoring.guru/pt-br/design-patterns/state

https://dev.to/adryannekelly/entendendo-state-pattern-flutter-3anp

https://en.wikipedia.org/wiki/Finite-state_machine

The Flutter Developer and the importance of native knowledge

Pedro Bueno — Thu, 21 Aug 2025 23:48:06 +0000

Hi, this article is an introductory and a little bit more theoretical. My purpose is to initiate a discussion about the need for studying mobile native development (iOS and Android native). I am available to chat about it on my Linkedin, my user is in/arcbueno

Almost a year ago,I started a post-graduation degree in Mobile Application Development. My purpose was deepen my knowledge in the study area that I want to be a specialist, focusing on what I didn’t know, because a lot of what I already do in my work was self-taught and my studying was dependent on what was required of me in the current project. If I didn't look for specific topics I would never have learned them, but to start, which topics? Native development first.
I have been working as a Android developer for 1 year before I started working with Flutter, but nothing too specific, just maintenance on an app that already existed. But it was working with Flutter that I really understood the importance of knowing Kotlin and Swift development (or Java and Objective-C if you prefer). And it’s about that importance that I would like to talk.

The native was already here before Flutter
It sounds like it's an obvious statement, but we should understand what it means: if native development already exists, so other applications, libraries and documentation were created before. We have many apps built, documentation written and active communities for questions, which makes it easier if your app needs to work with specific tools, such as gyroscope or accelerometer, for example.

This advantage also extends to its libraries as well, that they already tested and it is in use for long years, just in case that you are insecure about using that lib that only 10 people like and barely have 100 downloads on pub.dev.

It's normal to a programmer to sometimes “work on a deeper level” and work on something with more complexity. But if you need to go to native development, you will be glad to know the number of things that are already done.

Understand the configs helps a lot
When developing mobile applications its common the use of “flavorsˮ or developing environments (dev, staging, production), but Flutter creates apps for iOS, Android, Web, Windows… what to do?

That's why it's important to know how to configure, or at least understand the structure of an iOS and Android project. What the info.plist file does? What is this gradle that always complains to me when I add a new setting?

Yes, I know, you don't spend all of your day working on Android SDK version or cocoapods updates, but sometimes you'll have to have some contact with it and knowing its existence will help a lot. I'm not talking about someone that started studying mobile development less than a year ago and is still divided on which state management method to use. I'm talking about turning in an experienced developer that is capable of solving problems, even because there will be a time that the Apple's App Store will require a new setting and you need to understand what it may affect.

MethodChannels
In another moment I may talk about the technical part of MethodChannels, but, to resume, it's a feature of Flutter that allows your hybrid app update data with the Kotlin or Swift code (or C if you are working for desktop).

This is the center of our motivation, the “howˮ communicate with the native framework, because, as I already said, in some moment you'll have to.

An experience that I had was when I worked to an e-commerce platform, the company made a contract with a company of payment tools, but this tool's SDK only had support to Android and iOS, because Flutter was still a bit new for some companies. In this case, I had to use the native frameworks: I developed service classes and listeners to communicate with the Flutter app using MethodChannels.

It was an specific case, I know, but I will never forget that my lack of knowledge turned a 3 to 5 days work into 2 weeks work. This was a reminder that native development study isn't only a "plusˮ but will be the difference between delivering on time or a costly delay.

Higher accuracy on hardware data
Working with Flutter is cool, developing a code and running on Android and iOS devices without major problems helps the developer a lot, but we often have a hard time when accessing hardware data, as gyroscope or accelerometer or bluetooth, for example.

This difficulties are, in general, the performance to access data, or accuracy or a stable connection (in the bluetooth case). However, the use of MethodChannels + native development turned this way easier.

And we have to be fair: the files size are smaller and general performance of native are better. The hybrid development is easier and more practical, of course, but it's not that recommended for some application types for a reason. The communication with native development is the solution to bypass this cases.

So I should give up on Flutter and start being a native framework developer?
I don't mean that, I love Flutter, how it is growing and reaching popularity for many other reasons that are well structured. The Flutter framework has a lot of qualities that already influenced other languages like it made it easier the writing of UI, fast understanding and easy configuration. We just need to get the possible problems and bring it solution.

Conclusion
Sure, let's be fair, a developer that has 10 years of experience in mobile development already had contact with what we saw, but the ideal is that we don't need 10 years to have this understanding. Knowing how to solve problems is our job as developers and understanding that there isn't a “silver bulletˮ for everything when developing software is essential. Ultimately, it's not about choosing one or the other, but about expanding your arsenal of tools to become a truly well-rounded programmer.

Portuguese text: https://medium.com/cuscuzcomcodigo/o-desenvolvedor-flutter-e-a-import%C3%A2ncia-do-conhecimento-nativo-347d03b98abc