Comprehensive Flutter state management guidance covering built-in solutions, Provider, BLoC, and Riverpod. Use when working with state management, sharing data between widgets, managing app state, implementing reactive patterns, choosing state solutions, setState, ValueNotifier, ChangeNotifier, InheritedWidget, Provider package, BLoC pattern, Riverpod, state architecture, or comparing state management approaches.
From flutter-corenpx claudepluginhub aaronbassett/agent-foundry --plugin flutter-coreThis skill uses the workspace's default tool permissions.
examples/complex-state.mdexamples/simple-state.mdreferences/bloc-architecture.mdreferences/built-in-state.mdreferences/provider-patterns.mdreferences/riverpod-guide.mdreferences/state-comparison.mdSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Guides agent creation for Claude Code plugins with file templates, frontmatter specs (name, description, model), triggering examples, system prompts, and best practices.
A comprehensive guide to managing state in Flutter applications, from simple built-in solutions to sophisticated state management patterns. This skill helps you understand the state management landscape, choose the right solution for your needs, and implement it effectively.
Flutter's official philosophy advocates for a pragmatic approach to state management: start with the simplest solution that works, and graduate to more complex patterns only when your application's complexity demands it. This "simple-first" approach prevents over-engineering while ensuring your codebase can scale gracefully.
The key insight is that there is no single "best" state management solution—the right choice depends on your specific requirements, team size, application complexity, and architectural preferences.
Before choosing a state management solution, it's crucial to understand the fundamental distinction between two types of state in Flutter applications.
Ephemeral state (also called UI state or local state) is state that is scoped to a single widget and doesn't need to be shared across the app. This includes:
For ephemeral state, setState() is the recommended solution. It's simple, performant, and keeps your code straightforward. Don't reach for complex state management solutions when setState() will suffice.
App state (also called shared state or application state) is state that needs to be shared across multiple widgets or persisted beyond a single screen. This includes:
App state requires a dedicated state management approach to ensure data flows correctly through your widget tree and updates are propagated efficiently.
Flutter offers a spectrum of state management solutions, from built-in lightweight options to full-featured architectural patterns:
Use this decision tree to select the appropriate state management approach:
If ephemeral (widget-scoped):
→ Use setState() or ValueNotifier
→ No additional packages needed
→ Stop here—you're done!
If app state (shared across widgets): → Continue to Question 2
Simple app (1-3 screens, minimal shared state):
→ Use InheritedWidget or ValueNotifier with InheritedNotifier
→ Consider Provider if you want a cleaner API
→ References: Built-in State, Provider Patterns
Medium complexity (5-10 screens, moderate shared state): → Use Provider for simplicity and community support → Use Riverpod for type safety and modern features → References: Provider Patterns, Riverpod Guide
Large/Enterprise app (10+ screens, complex state flows): → Use Riverpod for flexibility and compile-time safety → Use BLoC for strict architecture and enterprise requirements → References: BLoC Architecture, State Comparison
Need event-driven architecture with audit trails? → Use BLoC (excellent for regulated industries) → Reference: BLoC Architecture
Want compile-time safety and no BuildContext dependency? → Use Riverpod (catches errors at compile time) → Reference: Riverpod Guide
Working with streams extensively? → Use BLoC or StreamBuilder with built-in solutions → Reference: Built-in State
Team prefers simple, familiar patterns? → Use Provider (gentle learning curve) → Reference: Provider Patterns
Regardless of which solution you choose, follow these principles:
Flutter uses a declarative paradigm where UI = f(state). Your UI should be a pure function of your state. Instead of imperatively updating widgets, change the state and let Flutter rebuild the affected widgets.
// Imperative (wrong approach)
void updateCounter() {
counterText.text = count.toString();
}
// Declarative (Flutter way)
void updateCounter() {
setState(() {
count++;
});
// UI automatically reflects the new state
}
Keep your business logic separate from your UI code. State management solutions should handle:
Your widgets should be thin presentation layers that react to state changes, not contain business logic.
Only rebuild widgets that actually depend on changed state. Use:
ValueListenableBuilder for single valuesConsumer or Selector in Providerref.watch() in Riverpod with granular dependenciesBlocBuilder in BLoCAvoid rebuilding entire screens when only a small portion needs to update.
State changes should be:
Async state (loading, error, data) is common in real applications. Use:
FutureBuilder and StreamBuilder for simple casesFutureProvider or Riverpod's AsyncValueThe classic Flutter counter demonstrates basic state management concepts. See how the same app can be implemented with different solutions: → Example: Simple State Examples
Form inputs, validation, and temporary UI state should generally stay local:
TextEditingController for text inputssetState() for validation stateUser login status is shared across the entire app:
Shopping carts demonstrate complex state with multiple operations:
Chat apps, live dashboards, and real-time updates:
StreamBuilder with built-in solutionsStreamProvider in Provider/RiverpodState management solutions can coexist in the same app, enabling gradual migration:
ChangeNotifier classes for that stateChangeNotifierProviderConsumer or Provider.of() to access stateProviderScope (can coexist with MultiProvider)@riverpod generators for new codeIf your current solution:
Then focus on new features rather than migration. Only migrate if you have clear pain points.
State management is closely tied to your app architecture:
ChangeNotifier or StateNotifier holding stateAll state management solutions should be thoroughly testable:
Test business logic independently of Flutter:
test('counter increments', () {
final counter = CounterNotifier();
counter.increment();
expect(counter.value, 1);
});
Test widgets with mocked state:
ProviderScope overridesProviderContainer with overridesBlocProvider.value() with test blocsTest complete features with real state management:
autoDispose in Riverpodconst constructors where possibleselect() or Selector for granular dependenciesshared_preferences for simple key-value datahive or sqflite for structured dataNow that you understand the state management landscape, explore specific solutions:
Start with Built-in State Solutions: → Built-in State → Simple State Examples
Choose between Provider and Riverpod: → Provider Patterns → Riverpod Guide → State Comparison
Consider BLoC for strict architecture: → BLoC Architecture → Complex State Examples
Compare all solutions: → State Comparison
State management is not about choosing the "best" solution—it's about choosing the right solution for your specific needs. Start simple with built-in solutions, and evolve your approach as your application grows in complexity. Focus on principles (declarative UI, separation of concerns, testability) rather than dogma about specific packages.