CINXE.COM

<!DOCTYPE html> <html lang="en"><head><script type="text/javascript" src="https://www.googletagmanager.com/gtm.js?id=GTM-MX6DBN9" async="async"></script><script type="text/javascript" src="/static/hash-o6oemknr/js/gtm.js"></script><meta charset="utf-8"/><meta http-equiv="X-UA-Compatible" content="IE=edge"/><meta name="viewport" content="width=device-width, height=device-height, initial-scale=1, user-scalable=no"/><meta name="generator" content="made with love by dartdoc"/><meta name="description" content="API docs for the Consumer class from the provider library, for the Dart programming language."/><title>Consumer class - provider library - Dart API</title><link rel="canonical" href="https://pub.dev/documentation/provider/latest/provider/Consumer-class.html"/><link rel="preconnect" href="https://fonts.gstatic.com"/><link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto+Mono:ital,wght@0,300;0,400;0,500;0,700;1,400&display=swap"/><link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0"/><link rel="stylesheet" href="/static/hash-o6oemknr/css/dartdoc.css"/><link rel="icon" href="/favicon.ico?hash=nk4nss8c7444fg0chird9erqef2vkhb8"/></head><body class="light-theme" data-base-href="../" data-using-base-href="false"><noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-MX6DBN9" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript><div id="overlay-under-drawer"></div><header id="title"><span id="sidenav-left-toggle" class="material-symbols-outlined" role="button" tabindex="0">menu</span><a class="hidden-xs" href="/"><img src="/static/hash-o6oemknr/img/dart-logo.svg" alt="" width="30" height="30" role="presentation" style="height: 30px; margin-right: 1em;"/></a><ol class="breadcrumbs gt-separated dark hidden-xs"><li><a href="/packages/provider">provider package</a></li><li><a href="../index.html">documentation</a></li><li><a href="../provider/provider-library.html">provider.dart</a></li><li class="self-crumb">Consumer<T> class</li></ol><div class="self-name">Consumer<T> class</div><form class="search navbar-right" role="search"><input id="search-box" class="form-control typeahead" type="text" placeholder="Loading search..." autocomplete="off"/></form><div id="theme-button" class="toggle" title="Toggle brightness"><label for="theme"><input id="theme" type="checkbox" value="light-theme"/><span id="dark-theme-button" class="material-symbols-outlined">dark_mode</span><span id="light-theme-button" class="material-symbols-outlined">light_mode</span></label></div></header><main><div id="dartdoc-main-content" class="main-content" data-above-sidebar="provider/provider-library-sidebar.html" data-below-sidebar="provider/Consumer-class-sidebar.html"> <div> <h1><span class="kind-class">Consumer<<wbr><span class="type-parameter">T</span>></span> class </h1></div> <div class="desc markdown markdown-body"> <p>Obtains <a href="../provider/Provider-class.html">Provider<T></a> from its ancestors and passes its value to <a href="../provider/Consumer/builder.html">builder</a>.</p> <p>The <a href="../provider/Consumer-class.html">Consumer</a> widget doesn't do any fancy work. It just calls <a href="../provider/Provider/of.html">Provider.of</a> in a new widget, and delegates its <code>build</code> implementation to <a href="../provider/Consumer/builder.html">builder</a>.</p> <p><a href="../provider/Consumer/builder.html">builder</a> must not be null and may be called multiple times (such as when the provided value change).</p> <p>The <a href="../provider/Consumer-class.html">Consumer</a> widget has two main purposes:</p> <ul> <li>It allows obtaining a value from a provider when we don't have a <a href="https://api.flutter.dev/flutter/widgets/BuildContext-class.html" rel="ugc">BuildContext</a> that is a descendant of said provider, and therefore cannot use <a href="../provider/Provider/of.html">Provider.of</a>.</li> </ul> <p>This scenario typically happens when the widget that creates the provider is also one of its consumers, like in the following example:</p> <pre class="language-dart"><code class="language-dart">@override Widget build(BuildContext context) { return ChangeNotifierProvider( create: (_) => Foo(), child: Text(Provider.of<Foo>(context).value), ); } </code></pre> <p>This example will throw a <a href="../provider/ProviderNotFoundException-class.html">ProviderNotFoundException</a>, because <a href="../provider/Provider/of.html">Provider.of</a> is called with a <a href="https://api.flutter.dev/flutter/widgets/BuildContext-class.html" rel="ugc">BuildContext</a> that is an ancestor of the provider.</p> <p>Instead, we can use the <a href="../provider/Consumer-class.html">Consumer</a> widget, that will call <a href="../provider/Provider/of.html">Provider.of</a> with its own <a href="https://api.flutter.dev/flutter/widgets/BuildContext-class.html" rel="ugc">BuildContext</a>.</p> <p>Using <a href="../provider/Consumer-class.html">Consumer</a>, the previous example will become:</p> <pre class="language-dart"><code class="language-dart">@override Widget build(BuildContext context) { return ChangeNotifierProvider( create: (_) => Foo(), child: Consumer<Foo>( builder: (_, foo, __) => Text(foo.value), }, ); } </code></pre> <p>This won't throw a <a href="../provider/ProviderNotFoundException-class.html">ProviderNotFoundException</a> and will correctly build the <a href="https://api.flutter.dev/flutter/widgets/Text-class.html" rel="ugc">Text</a>. It will also update the <a href="https://api.flutter.dev/flutter/widgets/Text-class.html" rel="ugc">Text</a> whenever the value <code>foo</code> changes.</p> <ul> <li>It helps with performance optimization by providing more granular rebuilds.</li> </ul> <p>Unless <code>listen: false</code> is passed to <a href="../provider/Provider/of.html">Provider.of</a>, the widget associated with the <a href="https://api.flutter.dev/flutter/widgets/BuildContext-class.html" rel="ugc">BuildContext</a> passed to <a href="../provider/Provider/of.html">Provider.of</a> will rebuild whenever the obtained value changes. This is the expected behavior, but sometimes it may rebuild more widgets than needed.</p> <p>Here's an example:</p> <pre class="language-dart"><code class="language-dart"> @override Widget build(BuildContext context) { return FooWidget( child: BarWidget( bar: Provider.of<Bar>(context), ), ); } </code></pre> <p>In the above code, only <code>BarWidget</code> depends on the value returned by <a href="../provider/Provider/of.html">Provider.of</a>. But when <code>Bar</code> changes, then both <code>BarWidget</code> <em>and</em> <code>FooWidget</code> will rebuild.</p> <p>Ideally, only <code>BarWidget</code> should be rebuilt. One solution to achieve that is to use <a href="../provider/Consumer-class.html">Consumer</a>.</p> <p>To do so, we will wrap <em>only</em> the widgets that depends on a provider into a <a href="../provider/Consumer-class.html">Consumer</a>:</p> <pre class="language-dart"><code class="language-dart"> @override Widget build(BuildContext context) { return FooWidget( child: Consumer<Bar>( builder: (_, bar, __) => BarWidget(bar: bar), ), ); } </code></pre> <p>In this situation, if <code>Bar</code> were to update, only <code>BarWidget</code> would rebuild.</p> <p>But what if it was <code>FooWidget</code> that depended on a provider? Example:</p> <pre class="language-dart"><code class="language-dart"> @override Widget build(BuildContext context) { return FooWidget( foo: Provider.of<Foo>(context), child: BarWidget(), ); } </code></pre> <p>Using <a href="../provider/Consumer-class.html">Consumer</a>, we can handle this kind of scenario using the optional <code>child</code> argument:</p> <pre class="language-dart"><code class="language-dart"> @override Widget build(BuildContext context) { return Consumer<Foo>( builder: (_, foo, child) => FooWidget(foo: foo, child: child), child: BarWidget(), ); } </code></pre> <p>In that example, <code>BarWidget</code> is built outside of <a href="../provider/Consumer/builder.html">builder</a>. Then, the <code>BarWidget</code> instance is passed to <a href="../provider/Consumer/builder.html">builder</a> as the last parameter.</p> <p>This means that when <a href="../provider/Consumer/builder.html">builder</a> is called again with new values, a new instance of <code>BarWidget</code> will not be created. This lets Flutter know that it doesn't have to rebuild <code>BarWidget</code>. Therefore in such a configuration, only <code>FooWidget</code> will rebuild if <code>Foo</code> changes.</p> <h2 id="note">Note:</h2> <p>The <a href="../provider/Consumer-class.html">Consumer</a> widget can also be used inside <a href="../provider/MultiProvider-class.html">MultiProvider</a>. To do so, it must return the <code>child</code> passed to <a href="../provider/Consumer/builder.html">builder</a> in the widget tree it creates.</p> <pre class="language-dart"><code class="language-dart">MultiProvider( providers: [ Provider(create: (_) => Foo()), Consumer<Foo>( builder: (context, foo, child) => Provider.value(value: foo.bar, child: child), ) ], ); </code></pre> <p>See also:</p> <ul> <li><a href="../provider/Selector-class.html">Selector</a>, a <a href="../provider/Consumer-class.html">Consumer</a> that can filter updates.</li> </ul> </div> <div> <dl class="dl-horizontal"> <dt>Inheritance</dt> <dd> <ul class="gt-separated dark clazz-relationships"> <li><a href="https://api.flutter.dev/flutter/dart-core/Object-class.html">Object</a></li> <li><a href="https://api.flutter.dev/flutter/foundation/DiagnosticableTree-class.html">DiagnosticableTree</a></li> <li><a href="https://api.flutter.dev/flutter/widgets/Widget-class.html">Widget</a></li> <li><a href="https://api.flutter.dev/flutter/widgets/StatelessWidget-class.html">StatelessWidget</a></li> <li><a href="../single_child_widget/SingleChildStatelessWidget-class.html">SingleChildStatelessWidget</a></li> <li>Consumer</li> </ul> </dd> </dl> </div> <div class="summary offset-anchor" id="constructors"> <h2>Constructors</h2> <dl class="constructor-summary-list"> <dt id="Consumer" class="callable"> <span class="name"><a href="../provider/Consumer/Consumer.html">Consumer</a></span><span class="signature">({<span class="parameter" id="-param-key"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/foundation/Key-class.html">Key</a>?</span> <span class="parameter-name">key</span>, </span><span class="parameter" id="-param-builder"><span>required</span> <span class="type-annotation"><a href="https://api.flutter.dev/flutter/widgets/Widget-class.html">Widget</a></span> <span class="parameter-name">builder</span>(<span class="parameter" id="param-context"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/widgets/BuildContext-class.html">BuildContext</a></span> <span class="parameter-name">context</span>, </span><span class="parameter" id="param-value"><span class="type-annotation">T</span> <span class="parameter-name">value</span>, </span><span class="parameter" id="param-child"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/widgets/Widget-class.html">Widget</a>?</span> <span class="parameter-name">child</span></span>), </span><span class="parameter" id="-param-child"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/widgets/Widget-class.html">Widget</a>?</span> <span class="parameter-name">child</span></span>})</span> </dt> <dd> Consumes a <a href="../provider/Provider-class.html">Provider<T></a> </dd> </dl> </div> <div class="summary offset-anchor" id="instance-properties"> <h2>Properties</h2> <dl class="properties"> <dt id="builder" class="property"> <span class="name"><a href="../provider/Consumer/builder.html">builder</a></span> <span class="signature">→ <a href="https://api.flutter.dev/flutter/widgets/Widget-class.html">Widget</a> Function<span class="signature">(<span class="parameter" id="param-context"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/widgets/BuildContext-class.html">BuildContext</a></span> <span class="parameter-name">context</span>, </span><span class="parameter" id="param-value"><span class="type-annotation">T</span> <span class="parameter-name">value</span>, </span><span class="parameter" id="param-child"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/widgets/Widget-class.html">Widget</a>?</span> <span class="parameter-name">child</span></span>)</span></span> </dt> <dd> Build a widget tree based on the value from a <a href="../provider/Provider-class.html">Provider<T></a>. <div class="features"><span class="feature">final</span></div> </dd> <dt id="hashCode" class="property inherited"> <span class="name"><a href="https://api.flutter.dev/flutter/widgets/Widget/hashCode.html">hashCode</a></span> <span class="signature">→ <a href="https://api.flutter.dev/flutter/dart-core/int-class.html">int</a></span> </dt> <dd class="inherited"> The hash code for this object. <div class="features"><span class="feature">no setter</span><span class="feature">inherited</span></div> </dd> <dt id="key" class="property inherited"> <span class="name"><a href="https://api.flutter.dev/flutter/widgets/Widget/key.html">key</a></span> <span class="signature">→ <a href="https://api.flutter.dev/flutter/foundation/Key-class.html">Key</a>?</span> </dt> <dd class="inherited"> Controls how one widget replaces another widget in the tree. <div class="features"><span class="feature">final</span><span class="feature">inherited</span></div> </dd> <dt id="runtimeType" class="property inherited"> <span class="name"><a href="https://api.flutter.dev/flutter/dart-core/Object/runtimeType.html">runtimeType</a></span> <span class="signature">→ <a href="https://api.flutter.dev/flutter/dart-core/Type-class.html">Type</a></span> </dt> <dd class="inherited"> A representation of the runtime type of the object. <div class="features"><span class="feature">no setter</span><span class="feature">inherited</span></div> </dd> </dl> </div> <div class="summary offset-anchor" id="instance-methods"> <h2>Methods</h2> <dl class="callables"> <dt id="build" class="callable inherited"> <span class="name"><a href="../single_child_widget/SingleChildStatelessWidget/build.html">build</a></span><span class="signature">(<wbr><span class="parameter" id="build-param-context"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/widgets/BuildContext-class.html">BuildContext</a></span> <span class="parameter-name">context</span></span>) <span class="returntype parameter">→ <a href="https://api.flutter.dev/flutter/widgets/Widget-class.html">Widget</a></span> </span> </dt> <dd class="inherited"> Describes the part of the user interface represented by this widget. <div class="features"><span class="feature">inherited</span></div> </dd> <dt id="buildWithChild" class="callable"> <span class="name"><a href="../provider/Consumer/buildWithChild.html">buildWithChild</a></span><span class="signature">(<wbr><span class="parameter" id="buildWithChild-param-context"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/widgets/BuildContext-class.html">BuildContext</a></span> <span class="parameter-name">context</span>, </span><span class="parameter" id="buildWithChild-param-child"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/widgets/Widget-class.html">Widget</a>?</span> <span class="parameter-name">child</span></span>) <span class="returntype parameter">→ <a href="https://api.flutter.dev/flutter/widgets/Widget-class.html">Widget</a></span> </span> </dt> <dd> A <a href="../single_child_widget/SingleChildStatelessWidget/build.html">build</a> method that receives an extra <code>child</code> parameter. <div class="features"><span class="feature">override</span></div> </dd> <dt id="createElement" class="callable inherited"> <span class="name"><a href="../single_child_widget/SingleChildStatelessWidget/createElement.html">createElement</a></span><span class="signature">(<wbr>) <span class="returntype parameter">→ <a href="../single_child_widget/SingleChildStatelessElement-class.html">SingleChildStatelessElement</a></span> </span> </dt> <dd class="inherited"> Creates a <a href="https://api.flutter.dev/flutter/widgets/StatelessElement-class.html" rel="ugc">StatelessElement</a> to manage this widget's location in the tree. <div class="features"><span class="feature">inherited</span></div> </dd> <dt id="debugDescribeChildren" class="callable inherited"> <span class="name"><a href="https://api.flutter.dev/flutter/foundation/DiagnosticableTree/debugDescribeChildren.html">debugDescribeChildren</a></span><span class="signature">(<wbr>) <span class="returntype parameter">→ <a href="https://api.flutter.dev/flutter/dart-core/List-class.html">List</a><span class="signature"><<wbr><span class="type-parameter"><a href="https://api.flutter.dev/flutter/foundation/DiagnosticsNode-class.html">DiagnosticsNode</a></span>></span></span> </span> </dt> <dd class="inherited"> Returns a list of <a href="https://api.flutter.dev/flutter/foundation/DiagnosticsNode-class.html" rel="ugc">DiagnosticsNode</a> objects describing this node's children. <div class="features"><span class="feature">inherited</span></div> </dd> <dt id="debugFillProperties" class="callable inherited"> <span class="name"><a href="https://api.flutter.dev/flutter/widgets/Widget/debugFillProperties.html">debugFillProperties</a></span><span class="signature">(<wbr><span class="parameter" id="debugFillProperties-param-properties"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/foundation/DiagnosticPropertiesBuilder-class.html">DiagnosticPropertiesBuilder</a></span> <span class="parameter-name">properties</span></span>) <span class="returntype parameter">→ void</span> </span> </dt> <dd class="inherited"> Add additional properties associated with the node. <div class="features"><span class="feature">inherited</span></div> </dd> <dt id="noSuchMethod" class="callable inherited"> <span class="name"><a href="https://api.flutter.dev/flutter/dart-core/Object/noSuchMethod.html">noSuchMethod</a></span><span class="signature">(<wbr><span class="parameter" id="noSuchMethod-param-invocation"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/Invocation-class.html">Invocation</a></span> <span class="parameter-name">invocation</span></span>) <span class="returntype parameter">→ dynamic</span> </span> </dt> <dd class="inherited"> Invoked when a nonexistent method or property is accessed. <div class="features"><span class="feature">inherited</span></div> </dd> <dt id="toDiagnosticsNode" class="callable inherited"> <span class="name"><a href="https://api.flutter.dev/flutter/foundation/DiagnosticableTree/toDiagnosticsNode.html">toDiagnosticsNode</a></span><span class="signature">(<wbr>{<span class="parameter" id="toDiagnosticsNode-param-name"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/String-class.html">String</a>?</span> <span class="parameter-name">name</span>, </span><span class="parameter" id="toDiagnosticsNode-param-style"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/foundation/DiagnosticsTreeStyle.html">DiagnosticsTreeStyle</a>?</span> <span class="parameter-name">style</span></span>}) <span class="returntype parameter">→ <a href="https://api.flutter.dev/flutter/foundation/DiagnosticsNode-class.html">DiagnosticsNode</a></span> </span> </dt> <dd class="inherited"> Returns a debug representation of the object that is used by debugging tools and by <a href="https://api.flutter.dev/flutter/foundation/DiagnosticsNode/toStringDeep.html" rel="ugc">DiagnosticsNode.toStringDeep</a>. <div class="features"><span class="feature">inherited</span></div> </dd> <dt id="toString" class="callable inherited"> <span class="name"><a href="https://api.flutter.dev/flutter/foundation/Diagnosticable/toString.html">toString</a></span><span class="signature">(<wbr>{<span class="parameter" id="toString-param-minLevel"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/foundation/DiagnosticLevel.html">DiagnosticLevel</a></span> <span class="parameter-name">minLevel</span> = <span class="default-value">DiagnosticLevel.info</span></span>}) <span class="returntype parameter">→ <a href="https://api.flutter.dev/flutter/dart-core/String-class.html">String</a></span> </span> </dt> <dd class="inherited"> A string representation of this object. <div class="features"><span class="feature">inherited</span></div> </dd> <dt id="toStringDeep" class="callable inherited"> <span class="name"><a href="https://api.flutter.dev/flutter/foundation/DiagnosticableTree/toStringDeep.html">toStringDeep</a></span><span class="signature">(<wbr>{<span class="parameter" id="toStringDeep-param-prefixLineOne"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/String-class.html">String</a></span> <span class="parameter-name">prefixLineOne</span> = <span class="default-value">''</span>, </span><span class="parameter" id="toStringDeep-param-prefixOtherLines"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/String-class.html">String</a>?</span> <span class="parameter-name">prefixOtherLines</span>, </span><span class="parameter" id="toStringDeep-param-minLevel"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/foundation/DiagnosticLevel.html">DiagnosticLevel</a></span> <span class="parameter-name">minLevel</span> = <span class="default-value">DiagnosticLevel.debug</span></span>}) <span class="returntype parameter">→ <a href="https://api.flutter.dev/flutter/dart-core/String-class.html">String</a></span> </span> </dt> <dd class="inherited"> Returns a string representation of this node and its descendants. <div class="features"><span class="feature">inherited</span></div> </dd> <dt id="toStringShallow" class="callable inherited"> <span class="name"><a href="https://api.flutter.dev/flutter/foundation/DiagnosticableTree/toStringShallow.html">toStringShallow</a></span><span class="signature">(<wbr>{<span class="parameter" id="toStringShallow-param-joiner"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/String-class.html">String</a></span> <span class="parameter-name">joiner</span> = <span class="default-value">', '</span>, </span><span class="parameter" id="toStringShallow-param-minLevel"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/foundation/DiagnosticLevel.html">DiagnosticLevel</a></span> <span class="parameter-name">minLevel</span> = <span class="default-value">DiagnosticLevel.debug</span></span>}) <span class="returntype parameter">→ <a href="https://api.flutter.dev/flutter/dart-core/String-class.html">String</a></span> </span> </dt> <dd class="inherited"> Returns a one-line detailed description of the object. <div class="features"><span class="feature">inherited</span></div> </dd> <dt id="toStringShort" class="callable inherited"> <span class="name"><a href="https://api.flutter.dev/flutter/widgets/Widget/toStringShort.html">toStringShort</a></span><span class="signature">(<wbr>) <span class="returntype parameter">→ <a href="https://api.flutter.dev/flutter/dart-core/String-class.html">String</a></span> </span> </dt> <dd class="inherited"> A short, textual description of this widget. <div class="features"><span class="feature">inherited</span></div> </dd> </dl> </div> <div class="summary offset-anchor inherited" id="operators"> <h2>Operators</h2> <dl class="callables"> <dt id="operator ==" class="callable inherited"> <span class="name"><a href="https://api.flutter.dev/flutter/widgets/Widget/operator_equals.html">operator ==</a></span><span class="signature">(<wbr><span class="parameter" id="==-param-other"><span class="type-annotation"><a href="https://api.flutter.dev/flutter/dart-core/Object-class.html">Object</a></span> <span class="parameter-name">other</span></span>) <span class="returntype parameter">→ <a href="https://api.flutter.dev/flutter/dart-core/bool-class.html">bool</a></span> </span> </dt> <dd class="inherited"> The equality operator. <div class="features"><span class="feature">inherited</span></div> </dd> </dl> </div> </div><div id="dartdoc-sidebar-left" class="sidebar sidebar-offcanvas-left"><header id="header-search-sidebar" class="hidden-l"><form class="search-sidebar" role="search"><input id="search-sidebar" class="form-control typeahead" type="text" placeholder="Loading search..." autocomplete="off"/></form></header><ol id="sidebar-nav" class="breadcrumbs gt-separated dark hidden-l"><li><a href="/packages/provider">provider package</a></li><li><a href="../index.html">documentation</a></li><li><a href="../provider/provider-library.html">provider</a></li><li class="self-crumb">Consumer<T> class</li></ol>  <h5>provider library</h5> <div id="dartdoc-sidebar-left-content"></div> </div><div id="dartdoc-sidebar-right" class="sidebar sidebar-offcanvas-right"> </div></main><footer><span class="no-break">provider 6.1.2</span></footer><script src="/static/hash-o6oemknr/dartdoc/resources/highlight.pack.js"></script><script src="/static/hash-o6oemknr/dartdoc/resources/docs.dart.js"></script></body></html>