ListenableBuilder class

A general-purpose widget for building a widget subtree when a Listenable changes.

ListenableBuilder is useful for more complex widgets that wish to listen to changes in other objects as part of a larger build function. To use ListenableBuilder, construct the widget and pass it a builder function.

Any subtype of Listenable (such as a ChangeNotifier, ValueNotifier, or Animation) can be used with a ListenableBuilder to rebuild only certain parts of a widget when the Listenable notifies its listeners. Although they have identical implementations, if an Animation is being listened to, consider using an AnimatedBuilder instead for better readability.

The following example uses a subclass of ChangeNotifier to hold the application model's state, in this case, a counter. A ListenableBuilder is then used to update the rendering (a Text widget) whenever the model changes.

To create a local project with this code sample, run:
flutter create --sample=widgets.ListenableBuilder.1 mysample

This version is identical, but using a ValueNotifier instead of a dedicated subclass of ChangeNotifier. This works well when there is only a single immutable value to be tracked.

To create a local project with this code sample, run:
flutter create --sample=widgets.ListenableBuilder.2 mysample

Performance optimizations

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

Performance is therefore improved by specifying any widgets that don't need to change using the prebuilt child attribute. The ListenableBuilder passes this child back to the builder callback so that it can be incorporated into the build.

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

This example shows how a ListenableBuilder can be used to listen to a FocusNode (which is also a ChangeNotifier) to see when a subtree has focus, and modify a decoration when its focus state changes. Only the Container is rebuilt when the FocusNode changes; the rest of the tree (notably the Focus widget) remain unchanged from frame to frame.

To create a local project with this code sample, run:
flutter create --sample=widgets.ListenableBuilder.3 mysample

Constructors

ListenableBuilder({Key? key, required Listenable listenable, required TransitionBuilder builder, Widget? child}): Creates a builder that responds to changes in listenable.
const

Properties

builder → TransitionBuilder: Called every time the listenable notifies about a change.
final
child → Widget?: The child widget to pass to the builder.
final
hashCode → int: The hash code for this object.
no setterinherited
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
listenable → Listenable: The Listenable supplied to the constructor.
no setteroverride
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

build(BuildContext context) → Widget: Override this method to build widgets that depend on the state of the listenable (e.g., the current value of the animation).
override
createElement() → StatefulElement: Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → State<AnimatedWidget>: Subclasses typically do not override this method.
inherited
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String: A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a one-line detailed description of the object.
inherited
toStringShort() → String: A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited