useCellNotifier<V> function
Returns a CellNotifier bound to cell, disposed on unmount.
useCellNotifier is the hooks layer's Listenable Bridge. It is the
flutter_hooks counterpart of CellNotifier itself — the value-notifier
adapter, not the widgets built on top of it. Use it when you want the
cell's value as a ValueListenable you can hand to another
flutter_hooks primitive or a Flutter widget, rather than as a rendered
subtree.
Why it is used
- Compose with
flutter_hooksprimitives:useValueListenable,useListenable,useValueChangedall take a Listenable or ValueListenable. Wrapping a cell inuseCellNotifierlets you feed the cell's value into them directly. - Hand the notifier to Flutter widgets:
ValueListenableBuilder,AnimatedBuilder,ListenableBuildertake aListenable. This hook is the correct way to obtain one from a cell inside aHookWidget. - Explicit lifecycle: the notifier is created once per cell (via
useMemoized) and disposed on unmount (viauseEffect), so its egress is released with the widget, not leaked.
When not to use it
- For rebuild-on-value-change, use useCellValue — it does the same work with less ceremony and no notifier to carry around.
- For rebuild-on-slice-change, use useCell — it adds CellSelector-style granularity.
- For async snapshots, use
useCellAsync.
How it works
useMemoizedconstructs one CellNotifier for the givencelland keeps it stable across builds. A change ofcellidentity produces a new notifier on the next build.useEffectregistersnotifier.disposeas the cleanup callback, which runs when the hook unmounts or when the notifier is replaced by auseMemoizedidentity change.
Technical Details
- Memoization key is
[cell]: the notifier is re-created only when the cell identity changes. Passing a freshly created cell on every build would defeat the memoization and rebuild the notifier each frame; the same caution applies here as toCellBuilder's cell-in-build anti-pattern. - The notifier is read-only:
CellNotifieroverridesvalue's setter to throw UnsupportedError. Mutate the cell directly (cell.value = ...) when a write is needed. - Error pulses are not surfaced: the notifier drops
pulse.type == 'error'on the floor. UseuseCellAsyncif the widget needs to render errors.
Example
class FancyView extends HookWidget {
final ValueCell<int> counter;
const FancyView({required this.counter, super.key});
@override
Widget build(BuildContext context) {
final notifier = useCellNotifier(counter);
useValueListenable(notifier);
return ValueListenableBuilder<int?>(
valueListenable: notifier,
builder: (_, v, __) => Text('$v'),
);
}
}
Parameters:
cell: The Source Cell. A ValueCell whose value the notifier mirrors. Held by reference for the notifier's lifetime; the notifier does not invalidate it on dispose.
Returns:
A CellNotifier that is stable across builds of the enclosing
HookWidget and disposed automatically on unmount.
See Also:
- useCell — the selector hook.
- useCellValue — the full-value shortcut.
CellNotifier— the underlying adapter; its docs cover the read-only contract in detail.- useValueListenable / useListenable — the
flutter_hooksprimitives this hook is typically composed with.
Implementation
CellNotifier<V> useCellNotifier<V>(ValueCell<V> cell) {
final notifier = useMemoized(() => CellNotifier<V>(cell), [cell]);
useEffect(() => notifier.dispose, [notifier]);
return notifier;
}