Cubit: Simple State Management in Flutter

Why it exists

State management in reactive frameworks can be complex. Sometimes you just need to manage a simple piece of state for a widget without the overhead of a full event-based system. Cubit was created as a simpler, more direct subset of the Bloc pattern for these common cases.

The mental model

Think of a Cubit as a specialized controller for a single piece of state. It holds the current state (e.g., the number 5) and exposes plain methods you can call (e.g., increment()). When a method is called, the Cubit computes the next state and broadcasts it to any part of the UI that is listening. It's a direct "call a function, get a new state" model.

How it works

You create a class that extends Cubit<StateType>, providing an initial state in the constructor. For example, class CounterCubit extends Cubit<int> { CounterCubit() : super(0); }. Inside this class, you define public methods that change the state. These methods use the built-in emit() function to push a new state value onto the Cubit's state stream. The state itself is a Stream, a sequence of asynchronous data that UI widgets like BlocBuilder can subscribe to and rebuild upon receiving new data.

When to use it

Use Cubit for simple, localized state management. It's perfect for managing the state of a counter, tracking the selected item in a filter, handling form inputs, or toggling a loading spinner. If your logic can be expressed as "when this function is called, emit this new state," Cubit is a great fit due to its simplicity.

When not to use it

Avoid Cubit when state logic is complex and benefits from being traceable. If you need to know why a state change occurred (e.g., was it UserTappedButtonEvent or DataLoadedEvent?), a full Bloc with its event-driven architecture is a better choice. Cubit functions are direct and imperative; they don't carry the semantic information that events do.

One canonical example

A simple counter Cubit exposes two methods, increment and decrement. Calling increment() calls emit(state + 1), which broadcasts the new integer value to all listeners.

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

void increment() => emit(state + 1);
void decrement() => emit(state - 1);
}

A UI widget would then listen to an instance of this Cubit and rebuild itself whenever the integer state changes.