StatefulWidget class Null safety

A widget that has mutable state.

A stateful widget is a widget that describes dynamic user interface. Stateful widgets are useful when the part of the user interface you are describing can change dynamically, e.g. due to having an internal state, or depending on some system state.

Performance consideration

Rad uses a extremely lightweight yet powerful mechanism to build and update DOM. Below are some general tips along with high level understanding of how things works under the hood:

  • Push the state to the leaves. Having state at top level of application is acceptable as well but it's worth noting that having less childs to update means updates can be dispatched and processed faster.
  • Use const constructors where possible. A rebuild process involves cascading a update call to all child widgets. Child widgets then can cascade update to their childs and so on. Every widget will update its corresponding DOM only if its description has changed. But when you use a const constructor, framework short circuit the rebuild process at the point where it encounters a constant.
  • In worst case, framework rebuild widgets from scratch. Complete rebuild involves disposing off current childs and rebuilding new ones with new state. Usually happens when child that framework is looking for is not there anymore because of state change in parent. Rebuilds might be bad if Rad has to render pixel multiple times a second. Luckly in Rad, building and updating interface is a one-step process. Framework handles the description of widgets and building process is carried out by the browser. We can rely on browsers for building big parts of tree when needed. After all that's what they do. By widget description, we mean 'data' that's required to build a widget. This means even if you remove child nodes/or part of DOM tree using browser inspector, calling setState() in a parent widget will bring back everything back in DOM.

A Stateful widget example: 'click to toggle'

class ClickToggle extends StatefulWidget {

  _ClickToggleState createState() => _ClickToggleState();

class _ClickToggleState extends State<ClickToggle> {
  bool isClicked = false;

  Widget build(BuildContext context) {
    return GestureDetector(
      onTap: _handleTap,
      child: Text(
            ? "on! click to turn off."
            : "click to turn on."

  _handleTap() {
    setState(() {
      isClicked = !isClicked;

See also:

  • StatelessWidget, for widgets that always build the same way given a particular configuration.


StatefulWidget({Key? key})


correspondingTag DomTagType?
Corresponding HTML tag to use to render this widget
@nonVirtual, read-only, override
hashCode int
The hash code for this object.
read-only, inherited
initialKey Key
final, inherited
runtimeType Type
A representation of the runtime type of the object.
read-only, inherited
widgetCaptureEventListeners Map<DomEventType, EventCallback?>
Events that this widget is listening to in capturing phase.
read-only, inherited
widgetChildren List<Widget>
Child widgets if any.
read-only, inherited
widgetEventListeners Map<DomEventType, EventCallback?>
Events that this widget is listening to.
read-only, inherited
widgetType String
Type of widget.
@nonVirtual, read-only, override


createConfiguration() WidgetConfiguration
Create widget's configuration.
createRenderObject(BuildContext context) RenderObject
Called when framework needs a RenderObject for current widget.
@nonVirtual, override
createState() State<StatefulWidget>
Creates the mutable state for this widget at a given location in the tree.
isConfigurationChanged(WidgetConfiguration oldConfiguration) bool
Whether configuration has changed.
@nonVirtual, override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a non-existent method or property is accessed.
toString() String
A string representation of this object.


operator ==(Object other) bool
The equality operator.