setState is the first state-management tool every Flutter developer learns, and it’s built directly into the framework — no package to add. Understanding exactly what it does (and its limits) is what tells you when it’s time to reach for something like Provider or Riverpod instead.
What setState Actually Does
Inside a StatefulWidget‘s State class, calling setState() tells Flutter: “a value used by this widget’s build() method changed, please rebuild it.” The callback you pass to setState is where you actually mutate the value — setState itself doesn’t know what changed, it just triggers a rebuild after the callback runs.
class CounterWidget extends StatefulWidget {
const CounterWidget({super.key});
@override
State<CounterWidget> createState() => _CounterWidgetState();
}
class _CounterWidgetState extends State<CounterWidget> {
int _count = 0;
void _increment() {
setState(() {
_count++;
});
}
@override
Widget build(BuildContext context) {
return ElevatedButton(
onPressed: _increment,
child: Text('Count: $_count'),
);
}
}
A common mistake: mutating _count outside the setState callback. The value does change, but Flutter is never told to rebuild, so the UI doesn’t update:
void _increment() {
_count++; // changes the value, but the UI won't reflect it
}
The Scope Problem
setState rebuilds the widget it’s called in (and its subtree) — nothing more, nothing less. That’s exactly what you want for state that’s local to one widget, like whether a card is expanded. It becomes awkward once two widgets that aren’t parent/child need to share the same value, because there’s no built-in mechanism to notify a sibling widget when setState runs elsewhere.
When setState Is Enough
setState is genuinely the right tool, not just a beginner stepping stone, for state that’s:
- Owned entirely by one widget (an animation controller’s progress, a form field’s focus state)
- Not needed anywhere else in the widget tree
- Simple enough that manually passing callbacks down to children (if any) isn’t painful
When to Move Past It
Once state needs to be read or changed by widgets that aren’t in a direct parent-child relationship, or once you’re passing the same callback down through four widget layers just to reach a deeply nested child, it’s time for a state management package. See our comparison of Provider, Riverpod, and Bloc for the tradeoffs between them.
