Consumer constructor

const Consumer({ Key? key, required ConsumerBuilder builder, Widget? child, })

Build a widget tree while listening to providers.

Consumer can be used to listen to providers inside a StatefulWidget or to rebuild as few widgets as possible when a provider updates.

As an example, consider:

final helloWorldProvider = Provider((_) => 'Hello world');

We can then use Consumer to listen to helloWorldProvider inside a StatefulWidget like so:

class Example extends StatefulWidget {
  @override
  _ExampleState createState() => _ExampleState();
}

class _ExampleState extends State<Example> {
  @override
  Widget build(BuildContext context) {
    return Consumer(
      builder: (context, ref, child) {
        final value = ref.watch(helloWorldProvider);
        return Text(value); // Hello world
      },
    );
  }
}

Note You can watch as many providers inside Consumer as you want to:

Consumer(
  builder: (context, ref, child) {
    final value = ref.watch(someProvider);
    final another = ref.watch(anotherProvider);
    ...
  },
);

Performance optimizations

If your builder function contains a subtree that does not depend on the animation, it is more efficient to build that subtree once instead of rebuilding it on every provider update.

If you pass the pre-built subtree as the child parameter, the Consumer will pass it back to your builder function so that you can incorporate it into your build.

Using this pre-built child is entirely optional, but can improve performance significantly in some cases and is therefore a good practice.

This sample shows how you could use a Consumer

final counterProvider = StateProvider((ref) => 0);

class MyHomePage extends ConsumerWidget {
  MyHomePage({Key? key, required this.title}) : super(key: key);
  final String title;

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    return Scaffold(
      appBar: AppBar(
        title: Text(title)
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text('You have pushed the button this many times:'),
            Consumer(
              builder: (BuildContext context, WidgetRef ref, Widget? child) {
                // This builder will only get called when the counterProvider
                // is updated.
                final count = ref.watch(counterProvider);

                return Row(
                  mainAxisAlignment: MainAxisAlignment.spaceEvenly,
                  children: <Widget>[
                    Text('$count'),
                    child!,
                  ],
                );
              },
              // The child parameter is most helpful if the child is
              // expensive to build and does not depend on the value from
              // the notifier.
              child: Text('Good job!'),
            )
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        child: Icon(Icons.plus_one),
        onPressed: () => ref.read(counterProvider.notifier).state++,
      ),
    );
  }
}

See also:

• ConsumerWidget, a base-class for widgets that wants to listen to providers.

Implementation

const Consumer({super.key, required ConsumerBuilder builder, Widget? child})
    : _child = child,
      _builder = builder;