collection_notifiers library

Collection classes with ChangeNotifier and ValueListenable support.

Reactive collection wrappers that notify listeners when their contents change, enabling efficient UI rebuilds in Flutter.

Notifiers

Every notifier ships with a matching flutter_hooks hook that owns the lifecycle: create on first build, dispose on unmount, rebuild the host widget on every change. Prefer the hooks — they remove the StatefulWidget / dispose / ValueListenableBuilder boilerplate that older Flutter docs lean on.

class Items extends HookWidget {
  const Items({super.key});

  @override
  Widget build(BuildContext context) {
    final items = useListNotifier<String>(['a', 'b', 'c']);
    return Column(
      children: [
        FilledButton(
          onPressed: () => items.add('d'),
          child: const Text('Add'),
        ),
        for (final item in items) Text(item),
      ],
    );
  }
}

Fallback: ValueListenableBuilder

When flutter_hooks is not on the project's dependency list — or when the notifier is owned by a state-management container such as a Riverpod ChangeNotifierProvider — the standard ValueListenableBuilder still works. It is a fallback, not a peer to the hook API.

Notification behaviour

Methods only call ChangeNotifier.notifyListeners when the collection actually changes:

  • set.add(existingElement) — no notification (already present)
  • map['key'] = sameValue — no notification (value unchanged)
  • list.clear() on an empty list — no notification (nothing to clear)

Exceptions: ListNotifier.sort and ListNotifier.shuffle on a list of length > 1 always notify, and MapNotifier.addEntries notifies only on length change. See each method's dartdoc for details.

Classes

ListNotifier<E>
A List implementation that notifies listeners when modified.
MapNotifier<K, V>
A Map implementation that notifies listeners when modified.
QueueNotifier<E>
A Queue implementation that notifies listeners when modified.
SetNotifier<E>
A Set implementation that notifies listeners when modified.

Functions

useListNotifier<E>([Iterable<E> initial = const []]) → ListNotifier<E>
Creates a ListNotifier tied to the widget lifecycle.
useMapNotifier<K, V>([Map<K, V> initial = const {}]) → MapNotifier<K, V>
Creates a MapNotifier tied to the widget lifecycle.
useQueueNotifier<E>([Iterable<E> initial = const []]) → QueueNotifier<E>
Creates a QueueNotifier tied to the widget lifecycle.
useSetNotifier<E>([Iterable<E> initial = const []]) → SetNotifier<E>
Creates a SetNotifier tied to the widget lifecycle.