---

name: bloc-pattern description: Master BLoC (Business Logic Component) pattern for Flutter with flutter_bloc. Learn events, states, testing, and advanced patterns for scalable apps.

BLoC Pattern in Flutter

Comprehensive guide to implementing the BLoC (Business Logic Component) pattern in Flutter for scalable, testable, and maintainable applications.

When to Use This Skill

• Building scalable Flutter applications
• Separating business logic from UI
• Implementing testable architecture
• Managing complex state
• Handling async operations
• Stream-based state management

Core BLoC Concepts

Events

User interactions or system events that trigger state changes

States

Representations of the app's state at any given moment

Transitions

The change from one state to another in response to an event

BLoC

The component that receives events and emits states

Implementation Patterns

1. Basic BLoC Setup

// Install dependencies in pubspec.yaml
// dependencies:
//   flutter_bloc: ^8.1.0
//   equatable: ^2.0.0

// Events
abstract class CounterEvent extends Equatable {
  @override
  List<Object?> get props => [];
}

class Increment extends CounterEvent {}
class Decrement extends CounterEvent {}

// States
class CounterState extends Equatable {
  final int count;

  const CounterState(this.count);

  @override
  List<Object?> get props => [count];
}

// BLoC
class CounterBloc extends Bloc<CounterEvent, CounterState> {
  CounterBloc() : super(const CounterState(0)) {
    on<Increment>((event, emit) => emit(CounterState(state.count + 1)));
    on<Decrement>((event, emit) => emit(CounterState(state.count - 1)));
  }
}

2. BLoC with API Integration

// Sealed classes for states (Dart 3+)
sealed class UserState extends Equatable {}

class UserInitial extends UserState {
  @override
  List<Object?> get props => [];
}

class UserLoading extends UserState {
  @override
  List<Object?> get props => [];
}

class UserLoaded extends UserState {
  final List<User> users;

  UserLoaded(this.users);

  @override
  List<Object?> get props => [users];
}

class UserError extends UserState {
  final String message;

  UserError(this.message);

  @override
  List<Object?> get props => [message];
}

// Events
sealed class UserEvent extends Equatable {}

class LoadUsers extends UserEvent {
  @override
  List<Object?> get props => [];
}

class RefreshUsers extends UserEvent {
  @override
  List<Object?> get props => [];
}

// BLoC with repository
class UserBloc extends Bloc<UserEvent, UserState> {
  final UserRepository repository;

  UserBloc({required this.repository}) : super(UserInitial()) {
    on<LoadUsers>(_onLoadUsers);
    on<RefreshUsers>(_onRefreshUsers);
  }

  Future<void> _onLoadUsers(LoadUsers event, Emitter<UserState> emit) async {
    emit(UserLoading());
    try {
      final users = await repository.fetchUsers();
      emit(UserLoaded(users));
    } catch (e) {
      emit(UserError(e.toString()));
    }
  }

  Future<void> _onRefreshUsers(RefreshUsers event, Emitter<UserState> emit) async {
    try {
      final users = await repository.fetchUsers();
      emit(UserLoaded(users));
    } catch (e) {
      emit(UserError(e.toString()));
    }
  }
}

3. BLoC Testing

// Install dev dependency
// dev_dependencies:
//   bloc_test: ^9.1.0

void main() {
  group('CounterBloc', () {
    late CounterBloc bloc;

    setUp(() {
      bloc = CounterBloc();
    });

    tearDown(() {
      bloc.close();
    });

    test('initial state is CounterState(0)', () {
      expect(bloc.state, const CounterState(0));
    });

    blocTest<CounterBloc, CounterState>(
      'emits [CounterState(1)] when Increment is added',
      build: () => CounterBloc(),
      act: (bloc) => bloc.add(Increment()),
      expect: () => [const CounterState(1)],
    );

    blocTest<CounterBloc, CounterState>(
      'emits [CounterState(-1)] when Decrement is added',
      build: () => CounterBloc(),
      act: (bloc) => bloc.add(Decrement()),
      expect: () => [const CounterState(-1)],
    );
  });

  group('UserBloc', () {
    late UserRepository mockRepository;
    late UserBloc bloc;

    setUp(() {
      mockRepository = MockUserRepository();
      bloc = UserBloc(repository: mockRepository);
    });

    tearDown(() {
      bloc.close();
    });

    blocTest<UserBloc, UserState>(
      'emits [UserLoading, UserLoaded] when LoadUsers succeeds',
      build: () {
        when(() => mockRepository.fetchUsers()).thenAnswer(
          (_) async => [User(id: '1', name: 'Test')],
        );
        return bloc;
      },
      act: (bloc) => bloc.add(LoadUsers()),
      expect: () => [
        UserLoading(),
        UserLoaded([User(id: '1', name: 'Test')]),
      ],
    );

    blocTest<UserBloc, UserState>(
      'emits [UserLoading, UserError] when LoadUsers fails',
      build: () {
        when(() => mockRepository.fetchUsers()).thenThrow(Exception('Failed'));
        return bloc;
      },
      act: (bloc) => bloc.add(LoadUsers()),
      expect: () => [
        UserLoading(),
        isA<UserError>(),
      ],
    );
  });
}

Best Practices

1. Use sealed classes for states and events (Dart 3+)
2. Implement Equatable for proper state comparison
3. Keep BLoC pure - no UI logic in BLoC
4. Use repositories for data access
5. Test thoroughly with bloc_test
6. Handle errors gracefully with error states
7. Dispose BLoCs properly
8. Use MultiBlocProvider for multiple BLoCs
9. Emit states based on business logic only
10. Document complex logic in BLoC

Resources

• https://bloclibrary.dev
• https://github.com/felangel/bloc