majiayu000 Riverpod — Consumers
Instructions
Consumers are widgets that give you a Ref (here, WidgetRef) so you can read and listen to providers. Without a Consumer, widgets cannot access the provider tree.
Consumer (builder)
Use Consumer when you want to keep extending StatelessWidget or StatefulWidget. The builder callback receives (context, ref, child).
class MyWidget extends StatelessWidget {
@override
Widget build(BuildContext context) {
return Consumer(
builder: (context, ref, _) {
final value = ref.watch(myProvider);
return Text(value.toString());
},
);
}
}
ConsumerWidget
Subclass ConsumerWidget instead of StatelessWidget. The build method receives (BuildContext context, WidgetRef ref).
class MyWidget extends ConsumerWidget {
@override
Widget build(BuildContext context, WidgetRef ref) {
final value = ref.watch(myProvider);
return Text(value.toString());
}
}
ConsumerStatefulWidget + ConsumerState
When you need a State (e.g. for lifecycle or local state), use ConsumerStatefulWidget and ConsumerState. The state object has a ref property.
class MyWidget extends ConsumerStatefulWidget {
@override
ConsumerState<MyWidget> createState() => _MyWidgetState();
}
class _MyWidgetState extends ConsumerState<MyWidget> {
@override
Widget build(BuildContext context) {
final value = ref.watch(myProvider);
return Text(value.toString());
}
}
Which to use
- Consumer — Use for everything if you prefer not to change your widget base class; slightly more verbose.
- ConsumerWidget — Recommended when you don't need State; one less nesting level.
- ConsumerStatefulWidget — Use when you need State (e.g. TabController, animations).
Why not StatelessWidget + context.watch?
Riverpod does not use BuildContext to watch providers because that would break auto-dispose and other features that rely on knowing when a widget stops listening. Ref-based consumers allow reliable disposal and correct behavior. The hooks_riverpod package also offers HookConsumerWidget etc. for use with flutter_hooks. Enable riverpod_lint for IDE refactors (e.g. "Convert to ConsumerWidget").