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.

Sample code

The following is a skeleton of a stateful widget subclass called YellowBird:

class YellowBird extends StatefulWidget {
  const YellowBird({ Key key }) : super(key: key);

  _YellowBirdState createState() => new _YellowBirdState();

class _YellowBirdState extends State<YellowBird> {
  Widget build(BuildContext context) {
    return new Container(color: const Color(0xFFFFE306));

In this example. the State has no actual state. State is normally represented as private member fields. Also, normally widgets have more constructor arguments, each of which corresponds to a final property.

The next example shows the more generic widget Bird which can be given a color and a child, and which has some internal state with a method that can be called to mutate it:

class Bird extends StatefulWidget {
  const Bird({
    Key key,
    this.color: const Color(0xFFFFE306),
  }) : super(key: key);

  final Color color;

  final Widget child;

  _BirdState createState() => new _BirdState();

class _BirdState extends State<Bird> {
  double _size = 1.0;

  void grow() {
    setState(() { _size += 0.1; });

  Widget build(BuildContext context) {
    return new Container(
      color: widget.color,
      transform: new Matrix4.diagonal3Values(_size, _size, 1.0),
      child: widget.child,

By convention, widget constructors only use named arguments. Named arguments can be marked as required using @required. Also by convention, the first argument is key, and the last argument is child, children, or the equivalent.

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.
Implemented by


StatefulWidget({Key key })
Initializes key for subclasses.


hashCode int
The 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


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. [...]
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. [...]
toString() String
Returns a string representation of this object.
toStringShort() String
A short, textual description of this widget.


operator ==(other) bool
The equality operator. [...]