Stateless and stateful widgets

Two kinds of widgets

Some parts of the screen never change by themselves: a logo, a label, a card that just shows the data given to it. These are StatelessWidgets: everything they show comes from their constructor arguments. Other parts change in response to the user or to data: a counter, a checkbox, a form, a loading spinner. These need state: data that can change while the widget is on screen. That is what StatefulWidget is for.

The counter, line by line

class CounterPage extends StatefulWidget {
  const CounterPage({super.key});

  @override
  State<CounterPage> createState() => _CounterPageState();
}

class _CounterPageState extends State<CounterPage> {
  int _cups = 0;                                  // the state

  void _addCup() {
    setState(() {                                 // tell Flutter the state changed
      _cups++;
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Chai counter')),
      body: Center(child: Text('Cups sold today: $_cups')),
      floatingActionButton: FloatingActionButton(
        onPressed: _addCup,
        child: const Icon(Icons.add),
      ),
    );
  }
}

1. CounterPage is the widget. It is immutable and only knows how to create its State.
2. _CounterPageState holds _cups. It lives as long as this part of the tree stays on screen.
3. Tapping the button calls _addCup, which changes _cups inside setState.
4. setState marks the widget as needing a rebuild; Flutter calls build again and the new number appears.

The State lifecycle

class _SearchState extends State<SearchPage> {
  final _controller = TextEditingController();
  Timer? _timer;

  @override
  void initState() {
    super.initState();
    _timer = Timer.periodic(const Duration(seconds: 30), (_) => _refresh());
  }

  Future<void> _refresh() async {
    final results = await fetchResults(_controller.text);   // slow call
    if (!mounted) return;                                   // the user may have left the screen
    setState(() => _results = results);
  }

  @override
  void dispose() {
    _timer?.cancel();
    _controller.dispose();
    super.dispose();
  }
  // ... build and _results omitted
}

mounted is true while the State is in the tree. If the user navigates away during a slow network call, calling setState afterwards would throw "setState() called after dispose()"; the mounted check prevents it.

Which one to choose

• Start with StatelessWidget. Switch to StatefulWidget only when the widget itself must remember changing data.
• Keep state as low in the tree as possible, so only a small part rebuilds.
• When several screens share state, move it into a state management solution (module 7) instead of passing it everywhere.

Common mistakes

• Changing state without setState: the screen does not update.
• Calling setState inside build: an infinite rebuild loop or an error.
• Forgetting dispose for controllers, timers and subscriptions: memory leaks.
• Calling setState after an await without checking mounted.