Widgets that make it easy to integrate blocs and cubits intoFlutter. Built to work withpackage:bloc.

Learn more atbloclibrary.dev!

*Note: All widgets exported by theflutter_bloc package integrate with bothCubit andBloc instances.

Sponsors#

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

Usage#

Lets take a look at how to useBlocProvider to provide aCounterCubit to aCounterPage and react to state changes withBlocBuilder.

counter_cubit.dart#

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

main.dart#

void main() => runApp(CounterApp());class CounterApp extends StatelessWidget {  @override  Widget build(BuildContext context) {    return MaterialApp(      home: BlocProvider(        create: (_) => CounterCubit(),        child: CounterPage(),      ),    );  }}

counter_page.dart#

class CounterPage extends StatelessWidget {  @override  Widget build(BuildContext context) {    return Scaffold(      appBar: AppBar(title: const Text('Counter')),      body: BlocBuilder<CounterCubit, int>(        builder: (context, count) => Center(child: Text('$count')),      ),      floatingActionButton: Column(        crossAxisAlignment: CrossAxisAlignment.end,        mainAxisAlignment: MainAxisAlignment.end,        children: <Widget>[          FloatingActionButton(            child: const Icon(Icons.add),            onPressed: () => context.read<CounterCubit>().increment(),          ),          const SizedBox(height: 4),          FloatingActionButton(            child: const Icon(Icons.remove),            onPressed: () => context.read<CounterCubit>().decrement(),          ),        ],      ),    );  }}

At this point we have successfully separated our presentational layer from our business logic layer. Notice that theCounterPage widget knows nothing about what happens when a user taps the buttons. The widget simply notifies theCounterCubit that the user has pressed either the increment or decrement button.

Bloc Widgets#

BlocBuilder#

BlocBuilder is a Flutter widget which requires abloc and abuilder function.BlocBuilder handles building the widget in response to new states.BlocBuilder is very similar toStreamBuilder but has a more simple API to reduce the amount of boilerplate code needed. Thebuilder function will potentially be called many times and should be apure function that returns a widget in response to the state.

SeeBlocListener if you want to "do" anything in response to state changes such as navigation, showing a dialog, etc...

If thebloc parameter is omitted,BlocBuilder will automatically perform a lookup usingBlocProvider and the currentBuildContext.

BlocBuilder<BlocA, BlocAState>(  builder: (context, state) {    // return widget here based on BlocA's state  })

Only specify the bloc if you wish to provide a bloc that will be scoped to a single widget and isn't accessible via a parentBlocProvider and the currentBuildContext.

BlocBuilder<BlocA, BlocAState>(  bloc: blocA, // provide the local bloc instance  builder: (context, state) {    // return widget here based on BlocA's state  })

For fine-grained control over when thebuilder function is called an optionalbuildWhen can be provided.buildWhen takes the previous bloc state and current bloc state and returns a boolean. IfbuildWhen returns true,builder will be called withstate and the widget will rebuild. IfbuildWhen returns false,builder will not be called withstate and no rebuild will occur.

BlocBuilder<BlocA, BlocAState>(  buildWhen: (previousState, state) {    // return true/false to determine whether or not    // to rebuild the widget with state  },  builder: (context, state) {    // return widget here based on BlocA's state  })

BlocSelector#

BlocSelector is a Flutter widget which is analogous toBlocBuilder but allows developers to filter updates by selecting a new value based on the current bloc state. Unnecessary builds are prevented if the selected value does not change. The selected value must be immutable in order forBlocSelector to accurately determine whetherbuilder should be called again.

If thebloc parameter is omitted,BlocSelector will automatically perform a lookup usingBlocProvider and the currentBuildContext.

BlocSelector<BlocA, BlocAState, SelectedState>(  selector: (state) {    // return selected state based on the provided state.  },  builder: (context, state) {    // return widget here based on the selected state.  },)

BlocProvider#

BlocProvider is a Flutter widget which provides a bloc to its children viaBlocProvider.of<T>(context). It is used as a dependency injection (DI) widget so that a single instance of a bloc can be provided to multiple widgets within a subtree.

In most cases,BlocProvider should be used to create new blocs which will be made available to the rest of the subtree. In this case, sinceBlocProvider is responsible for creating the bloc, it will automatically handle closing it.

BlocProvider(  create: (BuildContext context) => BlocA(),  child: ChildA(),);

By default, BlocProvider will create the bloc lazily, meaningcreate will get executed when the bloc is looked up viaBlocProvider.of<BlocA>(context).

To override this behavior and forcecreate to be run immediately,lazy can be set tofalse.

BlocProvider(  lazy: false,  create: (BuildContext context) => BlocA(),  child: ChildA(),);

In some cases,BlocProvider can be used to provide an existing bloc to a new portion of the widget tree. This will be most commonly used when an existingbloc needs to be made available to a new route. In this case,BlocProvider will not automatically close the bloc since it did not create it.

BlocProvider.value(  value: BlocProvider.of<BlocA>(context),  child: ScreenA(),);

then from eitherChildA, orScreenA we can retrieveBlocA with:

// with extensionscontext.read<BlocA>();// without extensionsBlocProvider.of<BlocA>(context);

The above snippets result in a one time lookup and the widget will not be notified of changes. To retrieve the instance and subscribe to subsequent state changes use:

// with extensionscontext.watch<BlocA>();// without extensionsBlocProvider.of<BlocA>(context, listen: true);

In addition,context.select can be used to retrieve part of a state and react to changes only when the selected part changes.

final isPositive = context.select((CounterBloc b) => b.state >= 0);

The snippet above will only rebuild if the state of theCounterBloc changes from positive to negative or vice versa and is functionally identical to using aBlocSelector.

MultiBlocProvider#

MultiBlocProvider is a Flutter widget that merges multipleBlocProvider widgets into one.MultiBlocProvider improves the readability and eliminates the need to nest multipleBlocProviders.By usingMultiBlocProvider we can go from:

BlocProvider<BlocA>(  create: (BuildContext context) => BlocA(),  child: BlocProvider<BlocB>(    create: (BuildContext context) => BlocB(),    child: BlocProvider<BlocC>(      create: (BuildContext context) => BlocC(),      child: ChildA(),    )  ))

to:

MultiBlocProvider(  providers: [    BlocProvider<BlocA>(      create: (BuildContext context) => BlocA(),    ),    BlocProvider<BlocB>(      create: (BuildContext context) => BlocB(),    ),    BlocProvider<BlocC>(      create: (BuildContext context) => BlocC(),    ),  ],  child: ChildA(),)

BlocListener#

BlocListener is a Flutter widget which takes aBlocWidgetListener and an optionalbloc and invokes thelistener in response to state changes in the bloc. It should be used for functionality that needs to occur once per state change such as navigation, showing aSnackBar, showing aDialog, etc...

listener is only called once for each state change (NOT including the initial state) unlikebuilder inBlocBuilder and is avoid function.

If the bloc parameter is omitted,BlocListener will automatically perform a lookup usingBlocProvider and the currentBuildContext.

BlocListener<BlocA, BlocAState>(  listener: (context, state) {    // do stuff here based on BlocA's state  },  child: Container(),)

Only specify the bloc if you wish to provide a bloc that is otherwise not accessible viaBlocProvider and the currentBuildContext.

BlocListener<BlocA, BlocAState>(  bloc: blocA,  listener: (context, state) {    // do stuff here based on BlocA's state  })

For fine-grained control over when thelistener function is called an optionallistenWhen can be provided.listenWhen takes the previous bloc state and current bloc state and returns a boolean. IflistenWhen returns true,listener will be called withstate. IflistenWhen returns false,listener will not be called withstate.

BlocListener<BlocA, BlocAState>(  listenWhen: (previousState, state) {    // return true/false to determine whether or not    // to call listener with state  },  listener: (context, state) {    // do stuff here based on BlocA's state  },  child: Container(),)

MultiBlocListener#

MultiBlocListener is a Flutter widget that merges multipleBlocListener widgets into one.MultiBlocListener improves the readability and eliminates the need to nest multipleBlocListeners.By usingMultiBlocListener we can go from:

BlocListener<BlocA, BlocAState>(  listener: (context, state) {},  child: BlocListener<BlocB, BlocBState>(    listener: (context, state) {},    child: BlocListener<BlocC, BlocCState>(      listener: (context, state) {},      child: ChildA(),    ),  ),)

to:

MultiBlocListener(  listeners: [    BlocListener<BlocA, BlocAState>(      listener: (context, state) {},    ),    BlocListener<BlocB, BlocBState>(      listener: (context, state) {},    ),    BlocListener<BlocC, BlocCState>(      listener: (context, state) {},    ),  ],  child: ChildA(),)

BlocConsumer#

BlocConsumer exposes abuilder andlistener in order react to new states.BlocConsumer is analogous to a nestedBlocListener andBlocBuilder but reduces the amount of boilerplate needed.BlocConsumer should only be used when it is necessary to both rebuild UI and execute other reactions to state changes in thebloc.BlocConsumer takes a requiredBlocWidgetBuilder andBlocWidgetListener and an optionalbloc,BlocBuilderCondition, andBlocListenerCondition.

If thebloc parameter is omitted,BlocConsumer will automatically perform a lookup usingBlocProvider and the currentBuildContext.

BlocConsumer<BlocA, BlocAState>(  listener: (context, state) {    // do stuff here based on BlocA's state  },  builder: (context, state) {    // return widget here based on BlocA's state  })

An optionallistenWhen andbuildWhen can be implemented for more granular control over whenlistener andbuilder are called. ThelistenWhen andbuildWhen will be invoked on eachblocstate change. They each take the previousstate and currentstate and must return abool which determines whether or not thebuilder and/orlistener function will be invoked. The previousstate will be initialized to thestate of thebloc when theBlocConsumer is initialized.listenWhen andbuildWhen are optional and if they aren't implemented, they will default totrue.

BlocConsumer<BlocA, BlocAState>(  listenWhen: (previous, current) {    // return true/false to determine whether or not    // to invoke listener with state  },  listener: (context, state) {    // do stuff here based on BlocA's state  },  buildWhen: (previous, current) {    // return true/false to determine whether or not    // to rebuild the widget with state  },  builder: (context, state) {    // return widget here based on BlocA's state  })

RepositoryProvider#

RepositoryProvider is a Flutter widget which provides a repository to its children viaRepositoryProvider.of<T>(context). It is used as a dependency injection (DI) widget so that a single instance of a repository can be provided to multiple widgets within a subtree.BlocProvider should be used to provide blocs whereasRepositoryProvider should only be used for repositories.

RepositoryProvider(  create: (context) => RepositoryA(),  child: ChildA(),);

then fromChildA we can retrieve theRepository instance with:

// with extensionscontext.read<RepositoryA>();// without extensionsRepositoryProvider.of<RepositoryA>(context)

Repositories that manage resources which must be disposed can do so via thedispose callback:

RepositoryProvider(  create: (context) => RepositoryA(),  dispose: (repository) => repository.dispose(),  child: ChildA(),);

MultiRepositoryProvider#

MultiRepositoryProvider is a Flutter widget that merges multipleRepositoryProvider widgets into one.MultiRepositoryProvider improves the readability and eliminates the need to nest multipleRepositoryProvider.By usingMultiRepositoryProvider we can go from:

RepositoryProvider<RepositoryA>(  create: (context) => RepositoryA(),  child: RepositoryProvider<RepositoryB>(    create: (context) => RepositoryB(),    child: RepositoryProvider<RepositoryC>(      create: (context) => RepositoryC(),      child: ChildA(),    )  ))

to:

MultiRepositoryProvider(  providers: [    RepositoryProvider<RepositoryA>(      create: (context) => RepositoryA(),    ),    RepositoryProvider<RepositoryB>(      create: (context) => RepositoryB(),    ),    RepositoryProvider<RepositoryC>(      create: (context) => RepositoryC(),    ),  ],  child: ChildA(),)

Gallery#

Examples#

• Counter - an example of how to create aCounterBloc to implement the classic Flutter Counter app.
• Form Validation - an example of how to use thebloc andflutter_bloc packages to implement form validation.
• Bloc with Stream - an example of how to hook up abloc to aStream and update the UI in response to data from theStream.
• Complex List - an example of how to manage a list of items and asynchronously delete items one at a time usingbloc andflutter_bloc.
• Infinite List - an example of how to use thebloc andflutter_bloc packages to implement an infinite scrolling list.
• Login Flow - an example of how to use thebloc andflutter_bloc packages to implement a Login Flow.
• Firebase Login - an example of how to use thebloc andflutter_bloc packages to implement login via Firebase.
• Github Search - an example of how to create a Github Search Application using thebloc andflutter_bloc packages.
• Weather - an example of how to create a Weather Application using thebloc andflutter_bloc packages. The app uses aRefreshIndicator to implement "pull-to-refresh" as well as dynamic theming.
• Todos - an example of how to create a Todos Application using thebloc andflutter_bloc packages.
• Timer - an example of how to create a Timer using thebloc andflutter_bloc packages.
• Shopping Cart - an example of how to create a Shopping Cart Application using thebloc andflutter_bloc packages based onflutter samples.
• Dynamic Form - an example of how to use thebloc andflutter_bloc packages to implement a dynamic form which pulls data from a repository.
• Wizard - an example of how to build a multi-step wizard using thebloc andflutter_bloc packages.
• Fluttersaurus - an example of how to use thebloc andflutter_bloc packages to create a thesuarus app -- made for Bytconf Flutter 2020.
• I/O Photo Booth - an example of how to use thebloc andflutter_bloc packages to create a virtual photo booth web app -- made for Google I/O 2021.
• I/O Pinball - an example of how to use thebloc andflutter_bloc packages to create a pinball web app -- made for Google I/O 2022.

Dart Versions#

• Dart 2: >= 2.14

Maintainers#

• Felix Angelov