SlotStatefulWidget

SlotStatefulWidget is the primary way to connect Flutter widgets to StateSlot values.

It allows a widget to:

  • declare which slots it depends on

  • rebuild when those slots change

  • stay independent from state ownership

This page explains how SlotStatefulWidget works and how it fits into the rebuild model described earlier.

What SlotStatefulWidget does

SlotStatefulWidget is a small helper on top of Flutter’s normal StatefulWidget.

Its job is simple:

  • register listeners for specified slots

  • register those listeners with a subscriber ID

  • call setState when notified

  • clean up listeners when the widget is disposed

It does not:

  • own state

  • store values

  • decide rebuild order

Those responsibilities stay where they belong.

What is a subscriber ID?

A subscriber ID is an internal identifier used to represent one widget instance.

SlotStatefulWidget automatically assigns one subscriber ID per widget state.

This ID is used to:

  • merge notifications from multiple slots

  • avoid duplicate rebuild requests

  • support batch updates

You usually do not need to manage subscriber IDs yourself.

They exist so that SimpleAppState can say:

> “This widget should rebuild now”

without caring which slot triggered the change.

Details of how notifications are grouped are explained in Rebuild Model.

Declaring slot dependencies

A widget declares its state dependencies by overriding the slots getter:

class CounterView extends SlotStatefulWidget {
  const CounterView({super.key});

  @override
  List<StateSlot> get slots => [count];

  @override
  SlotState<CounterView> createState() => _CounterViewState();
}

This declaration answers a simple question:

> “Which state slots should cause this widget to update?”

Nothing is inferred automatically. If a slot is not listed, the widget will not rebuild when that slot changes.

Reading slot values in build()

Inside build, you read slot values normally:

class _CounterViewState extends SlotState<CounterView> {
  @override
  Widget build(BuildContext context) {
    final value = count.get();

    return Text('Count: $value');
  }
}

Important points:

  • get() always returns a copy

  • reading does not subscribe implicitly

  • subscription is controlled only by slots

This keeps dependencies explicit and visible.

How rebuilds are triggered

When a listed slot changes:

  1. SimpleAppState notifies listeners

  2. SlotState receives the notification

  3. setState is called

  4. Flutter schedules a rebuild

After that, Flutter behaves normally.

SlotStatefulWidget does not bypass Flutter’s rebuild system.

Multiple slots, one widget

A widget can depend on multiple slots:

@override
List<StateSlot> get slots => [count, total];

If any of these slots change:

  • the widget is notified

  • setState is called

  • the widget rebuilds

During batch updates:

  • notifications are merged by subscriber ID

  • setState is requested only once per batch

Actual rebuild behavior is still controlled by Flutter.

Lifecycle and cleanup

SlotStatefulWidget handles listener cleanup automatically.

When the widget is disposed:

  • all registered listeners are removed

  • no stale callbacks remain

  • state continues to live independently

This prevents common issues such as:

  • memory leaks

  • updates to disposed widgets

  • unexpected rebuilds

Why this widget exists

Without SlotStatefulWidget, you would need to manually:

  • register listeners

  • manage subscriber IDs

  • call setState correctly

  • remove listeners on dispose

SlotStatefulWidget packages this logic into a small, explicit abstraction.

It is not required, but it is strongly recommended for clarity and safety.

What SlotStatefulWidget is not

SlotStatefulWidget is not:

  • a state container

  • a replacement for Flutter state

  • an implicit dependency tracker

  • a performance optimization trick

It is simply a bridge between StateSlot notifications and Flutter’s rebuild mechanism.

Summary

SlotStatefulWidget:

  • connects widgets to state slots

  • makes dependencies explicit

  • rebuilds widgets via normal Flutter rules

  • keeps state ownership outside the widget tree

If you understand how Flutter rebuilds widgets, SlotStatefulWidget will feel familiar.

It adds structure, not magic.