feat: Add `onAttach` to `Bloc` and `Cubit`

[feinstein]

As explained in #4161, the listener will only start to listen to events after initState has executed, which may lead to situations where events are not reflected in the screen.

In order to avoid this, we need to add some extra boilerplate in initState to only call our bloc/cubit initialization/load method in addPostFrameCallback.

In order to simplify this I would like to propose that Bloc and Cubit should expose a method onAttach to be optionally overridden. This method could be simply the private StreamController.onListen only firing once.

This will add a lifecycle to Bloc and Cubit, which plays well with the current close.

onAttach can be used for initialisations that need to happen once, when the Bloc/Cubit is added into a Widget and is being listened to.

Here's a simple implementation suggestion:

// ....

  BlocBase(this._state) {
    // ignore: invalid_use_of_protected_member
    _blocObserver.onCreate(this);
    _stateController.onListen(
      () {
        if (!_isAttached) {
          _isAttached = true;
          onAttach();
        }
      },
    );
  }

// ....

  bool _isAttached = false;

// ....

  @protected
  @visibleForTesting
  void onAttach();

[felangel]

Hi @feinstein 👋
Thanks for opening an issue!

I'm not sure I fully understand the problem this is attempting to solve. Can you please share a minimal reproduction sample that clearly illustrates the problem? I've never had to use addPostFrameCallback to make a listener work correctly so I suspect something else might be going on in your use case.

[feinstein]

Hey @felangel can you read the issue I am referring? It's all there.

[felangel]

Hey @felangel can you read the issue I am referring? It's all there.

I replied to the original issue and marked it as not planned since it sounded like there was no change needed. It would be very helpful if you could clearly demonstrate the problem with a minimal reproduction sample.

[feinstein]

In the original issue I was reporting what I thought it was a bug, how a listener only starts to listen after the bloc is listened by the widget after its mounted, which creates a window of time where events can be lost by a listener, if the bloc emits before its listener widget is mounted.

You explained how changing this could impact the expected behaviour of production apps and it would be a breaking change, and preferred to not change anything, as this became the normal behaviour.

Here's a reproducible example from that issue that illustrates the problem:

import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:freezed_annotation/freezed_annotation.dart';

part 'main.freezed.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const MyHomePage(title: 'Flutter Demo Home Page'),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});

  final String title;

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  final bloc = MyCubit();
  bool hasCalledListener = false;

  @override
  void initState() {
    super.initState();
    bloc.load();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        title: Text(widget.title),
      ),
      body: Center(
        child: BlocConsumer<MyCubit, MyState>(
          bloc: bloc,
          builder: (context, state) {
            return Column(
              mainAxisAlignment: MainAxisAlignment.center,
              children: <Widget>[
                Text(
                  '$state',
                  style: Theme.of(context).textTheme.headlineMedium,
                ),
                Text(
                  '$hasCalledListener',
                  style: Theme.of(context).textTheme.headlineMedium,
                ),
              ],
            );
          },
          listener: (context, state) {
            // This is not being called, even though the state changed from "loading" to "success".
            setState(() {
              hasCalledListener = true;
            });
          },
        ),
      ),
    );
  }
}

class MyCubit extends Cubit<MyState> {
  MyCubit() : super(const MyState.loading());

  Future<void> load() async {
    emit(const MyState.loading());
    // uncomment this line to make it work:
    // await Future.delayed(const Duration(seconds: 1), (){});
    emit(const MyState.success());
  }
}

@freezed
sealed class MyState with _$MyState {
  const factory MyState.loading() = MyStateLoading;

  const factory MyState.success() = MyStateSuccess;
}

This is a very common pattern in my apps. I call bloc.load in initState, and emit a new state for showing a loading spinner that is setup with a listener (I need to call an imperative method to show loading, like context.loader.show()). If my Cubit's load method emits the loading flag before an await, the loading never appears on screen, because the listener widget isn't mounted yet, so the event is lost.

The only way to fix this is to defer the loading event for when the widget is mounted and ready to listen to events. This can be done with an addPostFrameCallback.

In the original issue, I was reporting this behaviour as a bug, and I get that it would be a breaking change to change it. But in this issue, I am asking for an extra mechanism, that's not a breaking change, and would allow us to know when the bloc is ready to be listened, so we can start sending events to listeners.

This new mechanism is transparent to the current implementation, it only adds a lifecyle-ish event to a bloc, so we can do some actions only after we know there's a listener attached to listen and events won't be lost.

[tenhobi]

I want to make clear that Bloc itself works as intended, since as you can see you can add bloc to BlocBuilder and it will build the last known state to that bloc.

When we talk about listeners, they listen to event changes, and that means BlocListener must be mounted in Flutter for it to be able to detect changes. It works as stream listeners would.

---

You want "a listener", which is fired when mounting BlocListener/BlocBuilder/BlocConsumer, which means to always fire when the widget is mounted (and only when attached, similar to initState) and to have the current (last) state.

While your loading spinner might (and probably should) be hooked to BlocBuilder to show different UI (data vs loading) depending on your state, having onAttach one-time-callback (one-time-"listener") would maybe be beneficial in general to multiple users.

I think it should be simple as adding onAttach to BlocListener which would just call be called from _BlocListenerBaseState.initState since there we already collect current state in _previousState = _bloc.state; which is what @feinstein wants to be called.

@felangel do you think we could/should add such parameter?

[tenhobi]

This intent is also implemented in #4405 in a different way. Not really sure whether one-time-callback onAttach is better than flag startWithCurrentState. Maybe I like the flag a bit more.

[feinstein]

@tenhobi sorry if I gave you the impression I was claiming that Bloc was not working as intended, I am asking for extra functionality to avoid boiler plate.

I don't know what startWithCurrentState will do, so I can't comment if it's enough for my case, could you elaborate more please?

My initial idea was to add onAttach to the Bloc/Cubit class, because we can trigger any logic directly from there, bypassing the need to trigger the logic from the UI, by calling the cubit to start something. To me this handles better separation of concerns, as the Bloc will handle the page logic, and it can know when it can start sending events, since it will know that it's attached. Adding it in the widget is fine, I just feel it will require a bit more boilerplate logic, especially if e have multiple listeners using the same Bloc, now we need to be careful that only one calls bloc.load().

Now let me clarify some points you made because I think you misunderstood some of my issues:

You want "a listener", which is fired when mounting BlocListener/BlocBuilder/BlocConsumer, which means to always fire when the widget is mounted (and only when attached, similar to initState) and to have the current (last) state.

As I said, if we add the onAttach to the Bloc class itself, then I don't need the last state, the Bloc knows it's last state, so the API is simpler.

While your loading spinner might (and probably should) be hooked to BlocBuilder

My spinner has to be triggered by a function call, so it's not hooked to BlocBuilder, it's using a listener, since it has an imperative API, unfortunately. I am constrained by this and I can't change it.

I think it should be simple as adding onAttach to BlocListener which would just call be called from _BlocListenerBaseState.initState since there we already collect current state in _previousState = _bloc.state; which is what @feinstein wants to be called.

I really don't need the previous state, I just need to know when I can emit an event that won't be lost by the listener in the UI, because it's not mounted yet. My belief is that onAttach at the Bloc class is the best solution, but you are proposing it at the widget/UI level, which for me is acceptable, but I don't think it's optimal.

[tenhobi]

Okay, so your "onAttach" — which I initially understood in the sense of "widget mounted" — actually refers to "having a hook when someone starts listening to the bloc’s stream".

In theory, this is possible by exposing a callback like onListen from the internal BlocBase._stateController. However, to me this feels like an architectural antipattern, since the core principle of Bloc is that it should be driven solely by events — with a clear flow: events in, state out.

From a design perspective, it makes more sense (and aligns better with both Bloc and Flutter conventions) to have mechanisms like BlocListener optionally reacting to the current state upon subscription, rather than introducing internal lifecycle hooks into the Bloc itself.

That said, I understand the use case — it's about lazy initialization or performing side-effects only once the bloc is actually observed. If Felix agrees, adding this as an optional override (e.g. onFirstListener() or onStreamSubscribed()) is technically very feasible. Possibly it could be introduced together with an onCancel counterpart, reflecting the standard broadcast stream lifecycle. I personally don’t have strong objections to adding something like this, as long as it stays optional and doesn’t interfere with the typical event-driven flow of a Bloc.