flutter_bloc library
Flutter widgets that make it easy to implement the BLoC design pattern. Built to be used with the bloc state management package.
Get started at bloclibrary.dev 🚀
Classes
-
Bloc<
Event, State> -
Takes a
Stream
ofEvents
as input and transforms them into aStream
ofStates
as output. -
BlocBase<
State> - An interface for the core functionality implemented by both Bloc and Cubit.
-
BlocBuilder<
B extends StateStreamable< S> , S> -
BlocBuilder handles building a widget in response to new
states
. BlocBuilder is analogous to StreamBuilder but has simplified API to reduce the amount of boilerplate code needed as well as bloc-specific performance improvements. Please refer to BlocListener if you want to "do" anything in response tostate
changes such as navigation, showing a dialog, etc... -
BlocBuilderBase<
B extends StateStreamable< S> , S> - Base class for widgets that build themselves based on interaction with a specified bloc.
-
BlocConsumer<
B extends StateStreamable< S> , S> -
BlocConsumer exposes a builder and listener in order react to new
states.
BlocConsumer is analogous to a nested
BlocListener
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 the bloc. -
BlocEventSink<
Event extends Object?> - An ErrorSink that supports adding events.
-
BlocListener<
B extends StateStreamable< S> , S> -
Takes a BlocWidgetListener and an optional bloc and invokes
the listener in response to
state
changes in the bloc. It should be used for functionality that needs to occur only in response to astate
change such as navigation, showing aSnackBar
, showing aDialog
, etc... The listener is guaranteed to only be called once for eachstate
change unlike thebuilder
inBlocBuilder
. -
BlocListenerBase<
B extends StateStreamable< S> , S> - Base class for widgets that listen to state changes in a specified bloc.
- BlocObserver
- An interface for observing the behavior of Bloc instances.
- BlocOverrides
- This class facilitates overriding BlocObserver and EventTransformer. It should be extended by another class in client code with overrides that construct a custom implementation. The implementation in this class defaults to the base blocObserver and eventTransformer implementation. For example:
-
BlocProvider<
T extends StateStreamableSource< Object?> > -
Takes a
Create
function that is responsible for creating the Bloc or Cubit and a child which will have access to the instance viaBlocProvider.of(context)
. It is used as a dependency injection (DI) widget so that a single instance of a Bloc or Cubit can be provided to multiple widgets within a subtree. -
BlocSelector<
B extends StateStreamable< S> , S, T> - BlocSelector is analogous to BlocBuilder but allows developers to filter updates by selecting a new value based on the bloc state. Unnecessary builds are prevented if the selected value does not change.
-
Change<
State> -
A Change represents the change from one
State
to another. A Change consists of the currentState and nextState. - Closable
- An object that must be closed when no longer in use.
-
Cubit<
State> - A Cubit is similar to Bloc but has no notion of events and relies on methods to emit new states.
-
Emittable<
State extends Object?> - An object that can emit new states.
-
Emitter<
State> - An Emitter is a class which is capable of emitting new states.
- ErrorSink
- A generic destination for errors.
- MultiBlocListener
- Merges multiple BlocListener widgets into one widget tree.
- MultiBlocProvider
- Merges multiple BlocProvider widgets into one widget tree.
- MultiRepositoryProvider
- Merges multiple RepositoryProvider widgets into one widget tree.
-
RepositoryProvider<
T> -
Takes a
Create
function that is responsible for creating the repository and achild
which will have access to the repository viaRepositoryProvider.of(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. -
StateStreamable<
State> - A Streamable that provides synchronous access to the current state.
-
StateStreamableSource<
State> - A StateStreamable that must be closed when no longer in use.
-
Streamable<
State extends Object?> - An object that provides access to a stream of states over time.
-
Transition<
Event, State> - A Transition is the change from one state to another. Consists of the currentState, an event, and the nextState.
Extensions
- ReadContext on BuildContext
- Exposes the read method.
- SelectContext on BuildContext
-
Adds a
select
method on BuildContext. - WatchContext on BuildContext
- Exposes the watch method.
Typedefs
-
BlocBuilderCondition<
S> = bool Function(S previous, S current) -
Signature for the
buildWhen
function which takes the previousstate
and the currentstate
and is responsible for returning a bool which determines whether to rebuild BlocBuilder with the currentstate
. -
BlocListenerCondition<
S> = bool Function(S previous, S current) -
Signature for the
listenWhen
function which takes the previousstate
and the currentstate
and is responsible for returning a bool which determines whether or not to call BlocWidgetListener of BlocListener with the currentstate
. -
BlocWidgetBuilder<
S> = Widget Function(BuildContext context, S state) -
Signature for the
builder
function which takes theBuildContext
andstate
and is responsible for returning a widget which is to be rendered. This is analogous to thebuilder
function in StreamBuilder. -
BlocWidgetListener<
S> = void Function(BuildContext context, S state) -
Signature for the
listener
function which takes theBuildContext
along with thestate
and is responsible for executing in response tostate
changes. -
BlocWidgetSelector<
S, T> = T Function(S state) -
Signature for the
selector
function which is responsible for returning a selected value,T
, based onstate
. -
EventHandler<
Event, State> = FutureOr< void> Function(Event event, Emitter<State> emit) -
An event handler is responsible for reacting to an incoming
Event
and can emit zero or more states via the Emitter. -
EventMapper<
Event> = Stream< Event> Function(Event event) - Signature for a function which converts an incoming event into an outbound stream of events. Used when defining custom EventTransformers.
-
EventTransformer<
Event> = Stream< Event> Function(Stream<Event> events, EventMapper<Event> mapper) - Used to change how events are processed. By default events are processed concurrently.
Exceptions / Errors
- ProviderNotFoundException
-
The error that will be thrown if
Provider.of
fails to find aProvider
as an ancestor of the BuildContext used.