/flutter-change-notifier

name: flutter-change-notifier
description: "Use when setting up ChangeNotifier models, providing them to the widget tree, consuming state with Consumer or Provider.of, or optimizing rebuilds."
license: MIT

Flutter ChangeNotifier Skill

This skill defines how to correctly use `ChangeNotifier` with the `provider` package for state management in Flutter.

---

1. Model

Extend `ChangeNotifier` to manage state. Keep internal state **private** and expose **unmodifiable views**. Call `notifyListeners()` on every state change.

class CartModel extends ChangeNotifier {
  final List<Item> _items = [];

  UnmodifiableListView<Item> get items => UnmodifiableListView(_items);

  void add(Item item) {
    _items.add(item);
    notifyListeners();
  }

  void removeAll() {
    _items.clear();
    notifyListeners();
  }
}

• Place shared state **above** the widgets that use it in the widget tree.
• Never directly mutate widgets or call methods on them to change state — rebuild widgets with new data instead.

---

2. Providing the Model

ChangeNotifierProvider(
  create: (context) => CartModel(),
  child: MyApp(),
)

• `ChangeNotifierProvider` **automatically disposes** of the model when it is no longer needed.
• Use `MultiProvider` when you need to provide multiple models:

MultiProvider(
  providers: [
    ChangeNotifierProvider(create: (_) => CartModel()),
    ChangeNotifierProvider(create: (_) => UserModel()),
  ],
  child: MyApp(),
)

---

3. Consuming State

Consumer

Consumer<CartModel>(
  builder: (context, cart, child) => Stack(
    children: [
      if (child != null) child,
      Text('Total price: ${cart.totalPrice}'),
    ],
  ),
  child: const SomeExpensiveWidget(), // rebuilt only once
)

• Always specify the generic type (`Consumer<CartModel>`, not `Consumer`).
• Use the `child` parameter to pass **widgets that don't depend on the model** — they are built once and reused.
• Place `Consumer` widgets **as deep in the widget tree as possible** to minimize the scope of rebuilds:

HumongousWidget(
  child: AnotherMonstrousWidget(
    child: Consumer<CartModel>(
      builder: (context, cart, child) {
        return Text('Total price: ${cart.totalPrice}');
      },
    ),
  ),
)

Provider.of with listen: false

Use `Provider.of<T>(context, listen: false)` when you only need to **call methods** on the model, not react to state changes:

Provider.of<CartModel>(context, listen: false).removeAll();

---

4. Optimization Rules

• Do **not** wrap large widget subtrees in a `Consumer` if only a small part depends on the model.
• Avoid rebuilding widgets unnecessarily — structure your widget tree and provider usage carefully.
• Use `listen: false` in callbacks (e.g., `onPressed`) where you trigger actions but don't need rebuilds.

---

5. Testing

Write **unit tests** for your `ChangeNotifier` models to verify state changes and notifications:

test('adding item updates total', () {
  final cart = CartModel();
  var notified = false;
  cart.addListener(() => notified = true);

  cart.add(Item('Book'));

  expect(cart.items.length, 1);
  expect(notified, isTrue);
});

---

References

• [Flutter Website GitHub Repository](https://github.com/flutter/website)