When do you use a StatelessWidget versus a StatefulWidget?

A StatelessWidget has no mutable fields and builds from its properties plus inherited widgets. A StatefulWidget delegates to a State object, which persists across rebuilds and can call setState to schedule a new build. The widget is still immutable; the State holds the changing data.

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

  @override
  State<Counter> createState() => _CounterState();
}

class _CounterState extends State<Counter> {
  int count = 0;

  void increment() {
    setState(() {
      count += 1;
    });
  }

  @override
  Widget build(BuildContext context) {
    return TextButton(
      onPressed: increment,
      child: Text('Count: ' + count.toString()),
    );
  }
}

• Local ephemeral state such as a checkbox, animation or text controller belongs in State
• Shared application state is better held in a notifier, bloc or repository
• State should be disposed correctly, including controllers, subscriptions and tickers
• If only a child needs to rebuild, lift the state down or use a listenable builder

Common mistakes

Calling setState for values that do not affect the UI wastes frames. Starting async work in build causes repeated requests. Storing derived data in State invites inconsistency; compute it during build or in a getter when cheap.