Managing State in Flutter

Contents

• Core Concepts
• Architecture and Data Flow
• Workflow: Selecting a State Management Approach
• Workflow: Implementing MVVM with Provider
• Examples

Core Concepts

UI = f(state)

• Ephemeral State (Local State): State contained neatly within a single widget (e.g., current page in a

  PageView

  , current selected tab, animation progress). Manage this using a

  StatefulWidget

  and

  setState()

  .
• App State (Shared State): State shared across multiple parts of the app and maintained between user sessions (e.g., user preferences, login info, shopping cart contents). Manage this using advanced approaches like

  InheritedWidget

  , the

  provider

  package, and the MVVM architecture.

Architecture and Data Flow

• Unidirectional Data Flow (UDF): Enforce a strict flow where state flows down from the data layer, through the logic layer, to the UI layer. Events from user interactions flow up from the UI layer, to the logic layer, to the data layer.
• Single Source of Truth (SSOT): Ensure data changes always happen in the data layer (Repositories). The SSOT class must be the only class capable of modifying its respective data.
• Model (Data Layer): Handle low-level tasks like HTTP requests, data caching, and system resources using Repository classes.
• ViewModel (Logic Layer): Manage the UI state. Convert app data from the Model into UI State. Extend

  ChangeNotifier

  and call

  notifyListeners()

  to trigger UI rebuilds when data changes.
• View (UI Layer): Display the state provided by the ViewModel. Keep views lean; they should contain minimal logic (only routing, animations, or simple UI conditionals).

Workflow: Selecting a State Management Approach

• If managing Ephemeral State (single widget scope):
  1. Subclass

     StatefulWidget

     and

     State

     .
  2. Store mutable state as private fields within the

     State

     class.
  3. Mutate state exclusively inside a

     setState()

     callback to mark the widget as dirty and schedule a rebuild.
• If managing App State (shared across widgets):
  1. Implement the MVVM pattern.
  2. Use the

     provider

     package (a wrapper around

     InheritedWidget

     ) to inject state into the widget tree.
  3. Use

     ChangeNotifier

     to emit state updates.

Workflow: Implementing MVVM with Provider

provider

• 1. Define the Model (Repository).
• 2. Create the ViewModel (

  ChangeNotifier

  ).
• 3. Inject the ViewModel into the Widget Tree.
• 4. Consume the State in the View.
• 5. Validate the implementation.

1. Define the Model (Repository)

2. Create the ViewModel (

ChangeNotifier

)

ChangeNotifier

• Pass the Repository into the ViewModel via dependency injection.
• Define properties for the UI state (e.g.,

  isLoading

  ,

  data

  ,

  errorMessage

  ).
• Implement methods to handle UI events. Inside these methods, mutate the state and call

  notifyListeners()

  to trigger UI rebuilds.

3. Inject the ViewModel into the Widget Tree

ChangeNotifierProvider

provider

4. Consume the State in the View

StatelessWidget

StatefulWidget

• Use

  Consumer<MyViewModel>

  to rebuild specific parts of the UI when

  notifyListeners()

  is called.
• Use

  context.read<MyViewModel>()

  (or

  Provider.of<MyViewModel>(context, listen: false)

  ) inside event handlers (like

  onPressed

  ) to call ViewModel methods without triggering a rebuild of the calling widget.

5. Validate the implementation

1. Trigger a user action in the View.
2. Verify the ViewModel receives the event and calls the Repository.
3. Verify the Repository updates the SSOT and returns data.
4. Verify the ViewModel updates its state and calls

   notifyListeners()

   .
5. Verify the View rebuilds with the new state. Run validator -> review errors -> fix missing

   notifyListeners()

   calls or incorrect

   Provider

   scopes.

Examples

Ephemeral State Implementation (

setState

)

class EphemeralCounter extends StatefulWidget {
  const EphemeralCounter({super.key});

  @override
  State<EphemeralCounter> createState() => _EphemeralCounterState();
}

class _EphemeralCounterState extends State<EphemeralCounter> {
  int _counter = 0; // Local state

  void _increment() {
    setState(() {
      _counter++; // Mutate state and schedule rebuild
    });
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: _increment,
      child: Text('Count: $_counter'),
    );
  }
}

App State Implementation (MVVM + Provider)

// 1. Model (Repository)
class CartRepository {
  Future<void> saveItemToCart(String item) async {
    // Simulate network/database call
    await Future.delayed(const Duration(milliseconds: 500));
  }
}

// 2. ViewModel (ChangeNotifier)
class CartViewModel extends ChangeNotifier {
  final CartRepository repository;
  
  CartViewModel({required this.repository});

  final List<String> _items = [];
  bool isLoading = false;
  String? errorMessage;

  List<String> get items => List.unmodifiable(_items);

  Future<void> addItem(String item) async {
    isLoading = true;
    errorMessage = null;
    notifyListeners(); // Trigger loading UI

    try {
      await repository.saveItemToCart(item);
      _items.add(item);
    } catch (e) {
      errorMessage = 'Failed to add item';
    } finally {
      isLoading = false;
      notifyListeners(); // Trigger success/error UI
    }
  }
}

// 3. Injection & 4. View (UI)
class CartApp extends StatelessWidget {
  const CartApp({super.key});

  @override
  Widget build(BuildContext context) {
    // Inject ViewModel
    return ChangeNotifierProvider(
      create: (_) => CartViewModel(repository: CartRepository()),
      child: const CartScreen(),
    );
  }
}

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Consumer<CartViewModel>(
        builder: (context, viewModel, child) {
          if (viewModel.isLoading) {
            return const CircularProgressIndicator();
          }
          if (viewModel.errorMessage != null) {
            return Text(viewModel.errorMessage!);
          }
          return ListView.builder(
            itemCount: viewModel.items.length,
            itemBuilder: (_, index) => Text(viewModel.items[index]),
          );
        },
      ),
      floatingActionButton: FloatingActionButton(
        // Use read() to access methods without listening for rebuilds
        onPressed: () => context.read<CartViewModel>().addItem('New Item'),
        child: const Icon(Icons.add),
      ),
    );
  }
}