Flutter Bloc/Cubit State Management
Use this skill when building Flutter state management with bloc and flutter_bloc.
Core Rule
- Use
Cubit for simple, direct state updates.
- Use
Bloc for event-driven flows, transitions, and replayable business logic.
- Use
bloc in Dart-only projects.
- Use
flutter_bloc in Flutter apps when you need widgets like BlocProvider, BlocBuilder, or BlocListener.
- If you install
flutter_bloc, you do not need to add bloc separately in a Flutter app because flutter_bloc depends on it.
Decision Guide
Choose Cubit when:
- state changes are simple method calls
- you do not need events
- the feature is local and low complexity
- examples include counters, toggles, filters, form flags, and theme mode
Choose Bloc when:
- user actions should be modeled as explicit events
- the flow has loading, success, and failure transitions
- the logic benefits from clear state machines
- examples include auth, pagination, checkout, sync, and multi-step workflows
Required Project Setup
For Dart-only code:
- add
bloc
- do not add
flutter_bloc unless Flutter widgets are needed
For Flutter UI code:
- add
flutter_bloc
- let it bring
bloc transitively
- use
BlocProvider at the feature boundary
- use
BlocBuilder for rebuilds and BlocListener for side effects
Implementation Pattern
Prefer this structure:
- repository or service owns I/O
- bloc/cubit owns state and orchestration
- UI only dispatches actions and renders state
Keep state immutable.
Keep events explicit when using Bloc.
Keep one bloc or cubit per feature responsibility.
Lifecycle Rules
- Close manually created blocs and cubits with
close().
- Do not manually close instances owned by
BlocProvider.
- Use
BlocProvider or MultiBlocProvider to let Flutter manage disposal.
- If you create a bloc/cubit with
new or a constructor outside the widget tree, you own its lifecycle.
UI Binding Rules
Use BlocBuilder when the widget should rebuild from state.
Use BlocListener when the widget should react without rebuilding.
Use BlocConsumer only when both are needed in one place.
Use buildWhen and listenWhen when rebuilds or listeners need narrowing.
Use BlocSelector when only one field should drive rebuilds.
Testing Rules
- Test
Cubit by calling methods and asserting emitted states.
- Test
Bloc by adding events and asserting the transition sequence.
- Mock repositories at the boundary, not inside the bloc logic.
- Test side effects separately from rendering logic.
Common Pitfalls
- Do not put network calls directly in widgets.
- Do not use
Bloc for trivial local state.
- Do not add both
bloc and flutter_bloc in a Flutter app when only flutter_bloc is needed.
- Do not forget
close() for manually managed instances.
- Do not emit duplicate states unless the transition is meaningful.
- Do not let a single bloc grow into an app-wide dumping ground.
What To Prefer In Answers
When writing code or advising on design:
- show the smallest working Bloc or Cubit first
- mention why Bloc or Cubit was chosen
- mention whether the dependency should be
bloc or flutter_bloc
- include cleanup and testing notes if lifecycle is manual
- keep examples aligned with the current Flutter state management docs and the bloc package docs
Minimal Reference Checklist
bloc = core logic package
flutter_bloc = Flutter UI integration package
Cubit = method-based updates
Bloc = event-based transitions
- manual creation = manual
close()
- provider-owned instance = no manual
close()
1---
2name: bloc-cubit
3description: "Use when working with Flutter Bloc/Cubit state management. Covers when to choose Bloc vs Cubit, how to use bloc and flutter_bloc together, lifecycle, testing, and safe defaults."
4metadata:
5 revision: 1
6 updated-on: "2026-04-04"
7 source: https://skillmd.com/skills/andrewyng/bloc-cubit
8 upstream: official
9 tags: "flutter,dart,bloc,cubit,flutter_bloc,state-management,testing,architecture"
10---
11
12# Flutter Bloc/Cubit State Management
13
14Use this skill when building Flutter state management with `bloc` and `flutter_bloc`.
15
16## Core Rule
17
18- Use `Cubit` for simple, direct state updates.
19- Use `Bloc` for event-driven flows, transitions, and replayable business logic.
20- Use `bloc` in Dart-only projects.
21- Use `flutter_bloc` in Flutter apps when you need widgets like `BlocProvider`, `BlocBuilder`, or `BlocListener`.
22- If you install `flutter_bloc`, you do not need to add `bloc` separately in a Flutter app because `flutter_bloc` depends on it.
23
24## Decision Guide
25
26Choose `Cubit` when:
27- state changes are simple method calls
28- you do not need events
29- the feature is local and low complexity
30- examples include counters, toggles, filters, form flags, and theme mode
31
32Choose `Bloc` when:
33- user actions should be modeled as explicit events
34- the flow has loading, success, and failure transitions
35- the logic benefits from clear state machines
36- examples include auth, pagination, checkout, sync, and multi-step workflows
37
38## Required Project Setup
39
40For Dart-only code:
41- add `bloc`
42- do not add `flutter_bloc` unless Flutter widgets are needed
43
44For Flutter UI code:
45- add `flutter_bloc`
46- let it bring `bloc` transitively
47- use `BlocProvider` at the feature boundary
48- use `BlocBuilder` for rebuilds and `BlocListener` for side effects
49
50## Implementation Pattern
51
52Prefer this structure:
53- repository or service owns I/O
54- bloc/cubit owns state and orchestration
55- UI only dispatches actions and renders state
56
57Keep state immutable.
58Keep events explicit when using `Bloc`.
59Keep one bloc or cubit per feature responsibility.
60
61## Lifecycle Rules
62
63- Close manually created blocs and cubits with `close()`.
64- Do not manually close instances owned by `BlocProvider`.
65- Use `BlocProvider` or `MultiBlocProvider` to let Flutter manage disposal.
66- If you create a bloc/cubit with `new` or a constructor outside the widget tree, you own its lifecycle.
67
68## UI Binding Rules
69
70Use `BlocBuilder` when the widget should rebuild from state.
71Use `BlocListener` when the widget should react without rebuilding.
72Use `BlocConsumer` only when both are needed in one place.
73Use `buildWhen` and `listenWhen` when rebuilds or listeners need narrowing.
74Use `BlocSelector` when only one field should drive rebuilds.
75
76## Testing Rules
77
78- Test `Cubit` by calling methods and asserting emitted states.
79- Test `Bloc` by adding events and asserting the transition sequence.
80- Mock repositories at the boundary, not inside the bloc logic.
81- Test side effects separately from rendering logic.
82
83## Common Pitfalls
84
85- Do not put network calls directly in widgets.
86- Do not use `Bloc` for trivial local state.
87- Do not add both `bloc` and `flutter_bloc` in a Flutter app when only `flutter_bloc` is needed.
88- Do not forget `close()` for manually managed instances.
89- Do not emit duplicate states unless the transition is meaningful.
90- Do not let a single bloc grow into an app-wide dumping ground.
91
92## What To Prefer In Answers
93
94When writing code or advising on design:
95- show the smallest working Bloc or Cubit first
96- mention why Bloc or Cubit was chosen
97- mention whether the dependency should be `bloc` or `flutter_bloc`
98- include cleanup and testing notes if lifecycle is manual
99- keep examples aligned with the current Flutter state management docs and the bloc package docs
100
101## Minimal Reference Checklist
102
103- `bloc` = core logic package
104- `flutter_bloc` = Flutter UI integration package
105- `Cubit` = method-based updates
106- `Bloc` = event-based transitions
107- manual creation = manual `close()`
108- provider-owned instance = no manual `close()`