A widget that has mutable state.

State is information that (1) can be read synchronously when the widget is built and (2) might change during the lifetime of the widget. It is the responsibility of the widget implementer to ensure that the State is promptly notified when such state changes, using State.setState.

A stateful widget is a widget that describes part of the user interface by building a constellation of other widgets that describe the user interface more concretely. The building process continues recursively until the description of the user interface is fully concrete (e.g., consists entirely of RenderObjectWidgets, which describe concrete RenderObjects).

Stateful widget are useful when the part of the user interface you are describing can change dynamically, e.g. due to having an internal clock-driven state, or depending on some system state. For compositions that depend only on the configuration information in the object itself and the BuildContext in which the widget is inflated, consider using StatelessWidget.

StatefulWidget instances themselves are immutable and store their mutable state either in separate State objects that are created by the createState method, or in objects to which that State subscribes, for example Stream or ChangeNotifier objects, to which references are stored in final fields on the StatefulWidget itself.

The framework calls createState whenever it inflates a StatefulWidget, which means that multiple State objects might be associated with the same StatefulWidget if that widget has been inserted into the tree in multiple places. Similarly, if a StatefulWidget is removed from the tree and later inserted in to the tree again, the framework will call createState again to create a fresh State object, simplifying the lifecycle of State objects.

A StatefulWidget keeps the same State object when moving from one location in the tree to another if its creator used a GlobalKey for its key. Because a widget with a GlobalKey can be used in at most one location in the tree, a widget that uses a GlobalKey has at most one associated element. The framework takes advantage of this property when moving a widget with a global key from one location in the tree to another by grafting the (unique) subtree associated with that widget from the old location to the new location (instead of recreating the subtree at the new location). The State objects associated with StatefulWidget are grafted along with the rest of the subtree, which means the State object is reused (instead of being recreated) in the new location. However, in order to be eligible for grafting, the widget might be inserted into the new location in the same animation frame in which it was removed from the old location.

See also:

  • State, where the logic behind a StatefulWidget is hosted.
  • StatelessWidget, for widgets that always build the same way given a particular configuration and ambient state.
  • InheritedWidget, for widgets that introduce ambient state that can be read by descendant widgets.
Inheritance

Constructors

StatefulWidget({Key key })

Initializes key for subclasses.

const

Properties

hashCode int

Get a hash code for this object.

read-only, inherited
key Key

Controls how one widget replaces another widget in the tree.

final, inherited
runtimeType Type

A representation of the runtime type of the object.

read-only, inherited

Operators

operator ==(other) bool

The equality operator.

inherited

Methods

createElement() StatefulElement

Creates a StatefulElement to manage this widget's location in the tree.

createState() State

Creates the mutable state for this widget at a given location in the tree.

protected
debugFillDescription(List<String> description) → void

Add additional information to the given description for use by toString.

mustCallSuper, protected, inherited
noSuchMethod(Invocation invocation) → dynamic

Invoked when a non-existent method or property is accessed.

inherited
toString() String

Returns a string representation of this object.

inherited
toStringShort() String

A short, textual description of this widget.

inherited