bloc 7.0.0-nullsafety.2
bloc: ^7.0.0-nullsafety.2 copied to clipboard

Dart native js
Flutter Android iOS Linux macOS web Windows

A predictable state management library that helps implement the BLoC (Business Logic Component) design pattern.

build

Bloc

Pub build codecov Star on Github style: effective dart Flutter Website Awesome Flutter Flutter Samples License: MIT Discord Bloc Library


A dart package that helps implement the BLoC pattern.

Learn more at bloclibrary.dev!

This package is built to work with:


Sponsors #

Our top sponsors are shown below! [Become a Sponsor]


Try the Flutter Chat Tutorial  💬

Overview #

The goal of this package is to make it easy to implement the BLoC Design Pattern (Business Logic Component).

This design pattern helps to separate presentation from business logic. Following the BLoC pattern facilitates testability and reusability. This package abstracts reactive aspects of the pattern allowing developers to focus on writing the business logic.

Bloc #

Bloc Architecture

A Bloc is a type of Stream which converts incoming events into outgoing states.

Bloc Flow

State changes in bloc begin when events are added which triggers onEvent. The events are then funnelled through transformEvents. By default, transformEvents uses asyncExpand to ensure each event is processed in the order it was added but it can be overridden to manipulate the incoming event stream. mapEventToState is then invoked with the transformed events and is responsible for yielding states in response to the incoming events. transitions are then funnelled through transformTransitions which can be overridden to manipulation the outgoing state changes. Lastly, onTransition is called just before the state is updated and contains the current state, event, and next state.

Creating a Bloc

/// The events which `CounterBloc` will react to.
enum CounterEvent { increment }

/// A `CounterBloc` which handles converting `CounterEvent`s into `int`s.
class CounterBloc extends Bloc<CounterEvent, int> {
  /// The initial state of the `CounterBloc` is 0.
  CounterBloc() : super(0);

  @override
  Stream<int> mapEventToState(CounterEvent event) async* {
    switch (event) {
      /// When a `CounterEvent.increment` event is added,
      /// the current `state` of the bloc is accessed via the `state` property
      /// and a new state is emitted via `yield`.
      case CounterEvent.increment:
        yield state + 1;
        break;
    }
  }
}

Using a Bloc

void main() async {
  /// Create a `CounterBloc` instance.
  final bloc = CounterBloc();

  /// Access the state of the `bloc` via `state`.
  print(bloc.state); // 0

  /// Interact with the `bloc` to trigger `state` changes.
  bloc.add(CounterEvent.increment);

  /// Wait for next iteration of the event-loop
  /// to ensure event has been processed.
  await Future.delayed(Duration.zero);

  /// Access the new `state`.
  print(bloc.state); // 1

  /// Close the `bloc` when it is no longer needed.
  bloc.close();
}

Observing a Bloc

onEvent is called any time a new event is added to the bloc.

onTransition can be overridden to observe state changes for a single bloc.

onError can be overridden to observe errors for a single bloc.

enum CounterEvent { increment }

class CounterBloc extends Bloc<CounterEvent, int> {
  CounterBloc() : super(0);

  @override
  Stream<int> mapEventToState(CounterEvent event) async* {
    switch (event) {
      case CounterEvent.increment:
        yield state + 1;
        break;
    }
  }

  @override
  void onEvent(CounterEvent event) {
    super.onEvent(event);
    print(event);
  }

  @override
  void onTransition(Transition<CounterEvent, int> transition) {
    super.onTransition(transition);
    print(transition);
  }

  @override
  void onError(Object error, StackTrace stackTrace) {
    print('$error, $stackTrace');
    super.onError(error, stackTrace);
  }
}

BlocObserver can be used to observe all blocs.

class MyBlocObserver extends BlocObserver {
  @override
  void onCreate(Bloc bloc) {
    super.onCreate(bloc);
    print('onCreate -- bloc: ${bloc.runtimeType}');
  }

  @override
  void onEvent(Bloc bloc, Object? event) {
    super.onEvent(bloc, event);
    print('onEvent -- bloc: ${bloc.runtimeType}, event: $event');
  }

  @override
  void onTransition(Bloc bloc, Transition transition) {
    super.onTransition(bloc, transition);
    print('onTransition -- bloc: ${bloc.runtimeType}, transition: $transition');
  }

  @override
  void onError(Bloc bloc, Object error, StackTrace stackTrace) {
    print('onError -- bloc: ${bloc.runtimeType}, error: $error');
    super.onError(bloc, error, stackTrace);
  }

  @override
  void onClose(Bloc bloc) {
    super.onClose(bloc);
    print('onClose -- bloc: ${bloc.runtimeType}');
  }
}
void main() {
  Bloc.observer = MyBlocObserver();
  // Use blocs...
}

Cubit #

Cubit Architecture

A Cubit is a simplified Bloc which eliminates the notion of events and instead relies on methods to trigger state changes. Since Cubit extends Bloc, Cubit has the same public API as Bloc; however, rather than overriding mapEventToState, cubits can directly emit new states.

Cubit Flow

State changes in cubit begin with predefined function calls which can use the emit method to output new states. onTransition is called on each state change and contains the current and next state.

Creating a Cubit

/// A `CounterCubit` which manages an `int` as its state.
class CounterCubit extends Cubit<int> {
  /// The initial state of the `CounterCubit` is 0.
  CounterCubit() : super(0);

  /// When increment is called, the current state
  /// of the cubit is accessed via `state` and
  /// a new `state` is emitted via `emit`.
  void increment() => emit(state + 1);
}

Using a Cubit

void main() {
  /// Create a `CounterCubit` instance.
  final cubit = CounterCubit();

  /// Access the state of the `cubit` via `state`.
  print(cubit.state); // 0

  /// Interact with the `cubit` to trigger `state` changes.
  cubit.increment();

  /// Access the new `state`.
  print(cubit.state); // 1

  /// Close the `cubit` when it is no longer needed.
  cubit.close();
}

Observing a Cubit

Since all Cubits are Blocs, onTransition and onError can be overridden in a Cubit as well.

class CounterCubit extends Cubit<int> {
  CounterCubit() : super(0);

  void increment() => emit(state + 1);

  @override
  void onTransition(Transition<Null, int> transition) {
    super.onTransition(transition);
    print(transition);
  }

  @override
  void onError(Object error, StackTrace stackTrace) {
    print('$error, $stackTrace');
    super.onError(error, stackTrace);
  }
}

BlocObserver can be used to observe all cubits as well.

class MyBlocObserver extends BlocObserver {
  @override
  void onCreate(Bloc bloc) {
    super.onCreate(bloc);
    print('onCreate -- bloc: ${bloc.runtimeType}');
  }

  @override
  void onTransition(Bloc bloc, Transition transition) {
    super.onTransition(bloc, transition);
    print('onTransition -- bloc: ${bloc.runtimeType}, transition: $transition');
  }

  @override
  void onError(Bloc bloc, Object error, StackTrace stackTrace) {
    print('onError -- bloc: ${bloc.runtimeType}, error: $error');
    super.onError(bloc, error, stackTrace);
  }

  @override
  void onClose(Bloc bloc) {
    super.onClose(bloc);
    print('onClose -- bloc: ${bloc.runtimeType}');
  }
}
void main() {
  Bloc.observer = MyBlocObserver();
  // Use cubits...
}

Dart Versions #

  • Dart 2: >= 2.12.0-0

Examples #

  • Counter - an example of how to create a CounterBloc in a pure Dart app.

Maintainers #

810
likes
110
pub points
99%
popularity

Publisher

bloclibrary.dev

A predictable state management library that helps implement the BLoC (Business Logic Component) design pattern.

Homepage
Repository (GitHub)
View/report issues

Documentation

Documentation
API reference

License

MIT (LICENSE)

Dependencies

meta

More

Packages that depend on bloc