BLoC State Management (v9.x)

Goal

Strict separation of UI from business logic via event-driven unidirectional data flow. Choose Cubit (lightweight, no events) for simple state, or full Bloc (events + transformers) for complex flows.

Process

1. Install Dependencies

dependencies:
  flutter_bloc: ^9.1.1
  equatable: ^2.0.5
  bloc_concurrency: ^0.3.0  # For event transformers

dev_dependencies:
  bloc_test: ^10.0.0

2. Choose Pattern

3A. Implement Cubit

class CounterState extends Equatable {
  final int value;
  const CounterState({required this.value});
  @override
  List<Object?> get props => [value];
}

class CounterCubit extends Cubit<CounterState> {
  CounterCubit() : super(const CounterState(value: 0));
  void increment() => emit(CounterState(value: state.value + 1));
  void decrement() => emit(CounterState(value: state.value - 1));
}

3B. Implement Bloc

abstract class CounterEvent extends Equatable {
  const CounterEvent();
  @override
  List<Object?> get props => [];
}
class CounterIncremented extends CounterEvent {}
class CounterDecremented extends CounterEvent {}

class CounterBloc extends Bloc<CounterEvent, CounterState> {
  CounterBloc() : super(const CounterState(value: 0)) {
    on<CounterIncremented>((e, emit) => emit(CounterState(value: state.value + 1)));
    on<CounterDecremented>((e, emit) => emit(CounterState(value: state.value - 1)));
  }
}

4. Provide to Widget Tree

MultiBlocProvider(
  providers: [
    BlocProvider(create: (context) => CounterCubit()),
    BlocProvider(create: (context) => AuthBloc()),
  ],
  child: MyApp(),
)

5. Consume State

// Trigger events
context.read<CounterBloc>().add(CounterIncremented());
context.read<CounterCubit>().increment(); // Cubit: direct method call

See BLoC Best Practices for full widget examples with buildWhen/listenWhen.

6. Event Transformers

import 'package:bloc_concurrency/bloc_concurrency.dart';

on<SearchQueryChanged>(_onQueryChanged, transformer: restartable());
on<FormSubmitted>(_onFormSubmitted, transformer: droppable());

See BLoC Best Practices for custom debounce transformer.

7. Freezed Integration

Use Freezed for sealed union states with exhaustive when/map pattern matching. See BLoC Best Practices for full Freezed setup and examples.

8. Common Errors

See Error Handling & Common Pitfalls for solutions to:

• Emitting after Bloc close (emit.isDone guard)
• Mutable state causing silent UI bugs (spread into new instances)
• Scattered try/catch — use onError + addError instead

Reference Documentation

• BLoC Best Practices (v9.x) — Transformers, Freezed, testing with blocTest, hydrated/replay packages
• Error Handling & Common Pitfalls — Three common errors with before/after fixes
• State Management Overview — Cubit vs Provider/MVVM comparison

Constraints

• Immutable States: All states MUST be immutable. Use Equatable or Freezed.
• No UI in Bloc: Blocs/Cubits MUST NOT import Flutter widgets or BuildContext.
• Single Responsibility: Each Bloc handles one feature domain.
• Event Naming: Past tense nouns (UserLoggedIn, not UserLogin).
• State Naming: Nouns or adjectives (AuthSuccess, not AuthSucceeded).
• Always Close: Blocs/Cubits MUST be closed on dispose to prevent memory leaks.