# Flutter Change Notifier

> Flutter Change Notifier is an Agent Skill for development published in the evanca/flutter-ai-rules repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when setting up ChangeNotifier models, providing them to the widget tree, consuming state with Consumer or Provider.of, or optimizing rebuilds.

- Skill name: `flutter-change-notifier`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/evanca/flutter-ai-rules/blob/HEAD/skills/flutter-change-notifier/SKILL.md
- Repository: evanca/flutter-ai-rules (589 GitHub stars when collected)

## SKILL.md

# 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.

```dart
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

```dart
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:

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

---

## 3. Consuming State

### Consumer

```dart
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:

```dart
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:

```dart
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:

```dart
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)

---

Source: https://www.openparable.com/skill/development/flutter-change-notifier (OpenParable). Cite the canonical URL above.
