riverpod-containers

Riverpod — Containers / Scopes

Instructions

Providers themselves hold no state. State is stored in a ProviderContainer. In Flutter you use the ProviderScope widget, which creates and exposes a container to the widget tree.

Flutter: ProviderScope

Wrap your app at the root so widgets can read providers:

void main() {
  runApp(
    ProviderScope(
      child: MyApp(),
    ),
  );
}

After that, use Consumer / ConsumerWidget / ConsumerStatefulWidget to get a ref and call ref.watch / ref.read. You can also pass overrides or observers to ProviderScope.

Pure Dart: ProviderContainer

In command-line or server-side Dart, create a container, use it, then dispose it:

void main() {
  final container = ProviderContainer();
  try {
    final sub = container.listen(counterProvider, (previous, next) {
      print('Counter changed from $previous to $next');
    });
    print('Counter starts at ${sub.read()}');
  } finally {
    container.dispose();
  }
}

Why state lives in a container

• Separation of concerns — Only the provider (and ref) can change its state; the UI typically calls notifier methods.
• Testing — Each test can create a new container (e.g. ProviderContainer.test()) for a fresh state; no shared global state.
• Configuration — Overrides and observers are set on the container/scope. See riverpod-overrides and riverpod-observers.
• Scoping — The same provider can resolve to different state in different parts of the tree (advanced). See riverpod-scoping.

Testing

Do not use ProviderContainer() directly in tests. Use ProviderContainer.test() so the container is disposed when the test ends:

test('Counter starts at 0 and can be incremented', () {
  final container = ProviderContainer.test();
  expect(container.read(counterProvider), 0);
  container.read(counterProvider.notifier).increment();
  expect(container.read(counterProvider), 1);
});

In widget tests, wrap the widget in ProviderScope and use tester.container() to get the container if needed (see riverpod-testing).