New to Rust? Grab our free Rust for Beginners eBook Get it free →
Flutter State Management: setState

When a button changes a number on screen, the displayed value needs to follow the update. Flutter’s setState method tells Flutter that the widget subtree rooted at a State object may need rebuilding after its data changes.
In this article, I’ll explain Flutter state management and show how to update a counter with setState.
What is Flutter state management?
Change a field owned by a State object inside setState, and Flutter schedules that object’s subtree to rebuild.
- Use a StatefulWidget when a value changes while the widget is on screen.
- Keep the setState callback synchronous and limited to the state mutation.
- Use another state approach when multiple distant widgets need the same value.
What setState changes in Flutter
State is the data a widget needs to produce its current interface. A StatefulWidget pairs immutable configuration with a State object that can hold changing values.
| State type | Where it fits | Example |
|---|---|---|
| Ephemeral or local state | One widget owns and renders the value | Selected tab or counter |
| App or shared state | Multiple areas need the same value or it must persist | Login information or preferences |
Calling setState runs its callback immediately, then tells Flutter that this State object’s UI may need a new build. Flutter does not reload the whole app. It schedules a rebuild for the widget subtree rooted at that State object, so keep that object near the UI that depends on the value.
For example, a counter value used by one screen can live in that screen’s State. A login status shared by many screens may need app-level state instead. Flutter’s guidance treats this as a design choice based on where the value is used and whether it must survive beyond one widget.
What you need before using setState
This example needs a Flutter project and a StatefulWidget whose State object owns the integer displayed on screen. It uses Flutter’s Material library and no third-party state package.
- Put the changing field in the State subclass, not in a StatelessWidget.
- Change the field in response to an event such as a button press.
- Make the callback passed to setState synchronous. Do asynchronous work before or after it.
How to update a Flutter counter with setState
The counter keeps one integer in State, changes it when the button is pressed, and displays the latest value in the same widget subtree.
Step 1: Create a StatefulWidget and State field
A StatefulWidget keeps the counter in its State object, where the changing value drives the displayed number.
import 'package:flutter/material.dart'; // => Flutter Material UI
void main() {
runApp(const MaterialApp(home: CounterPage()));
}
class CounterPage extends StatefulWidget {
const CounterPage({super.key});
@override
State<CounterPage> createState() => _CounterPageState();
}
class _CounterPageState extends State<CounterPage> {
int _count = 0;
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Counter')),
body: Center(child: Text('Count: $_count')),
floatingActionButton: FloatingActionButton(
onPressed: () {
setState(() {
_count++;
});
},
child: const Icon(Icons.add),
),
);
}
}
The field starts at zero and supplies the number shown in the Text widget. The button callback increments it.
Step 2: Change the field inside setState
Keep only the field mutation inside the callback. Network requests and awaits belong outside it.
setState(() {
_count++;
});
Flutter calls this callback synchronously, then schedules a build for the State object. If an operation requires await, do it outside the callback and use setState only for the resulting synchronous field update.
Step 3: Run and verify the visible count
The expected behavior is that the displayed number increases by one after each tap. The Flutter SDK is not installed on this server, so this app could not be run here.
Check that the number shown in the Text widget matches the State field after the button callback.
Why setState may not update the UI
If the displayed value stays the same, check which State object owns the field and whether the widget displaying it belongs to that object’s subtree.
| Symptom | Check | Correction |
|---|---|---|
| Value changes but text does not | Is the field in the State object used by the displayed widget? | Move the field to the owning State or pass the value to the child. |
| “setState() or markNeedsBuild() called during build” | Is setState being called while build is already running? | Trigger the change from an event or schedule it outside the current build. |
| Callback contains await | Does the setState callback return a Future? | Await the operation outside setState, then update the field synchronously. |
| setState called after dispose | Can a timer, listener, or async operation outlive this State? | Cancel the work when disposing the State instead of relying only on mounted. |
Flutter’s API says a callback passed to setState must not be async, and calling the method after dispose is an error. Keep expensive work outside the callback because the method is for notifying Flutter about the state mutation, not for doing the associated computation.
A local counter is a good fit because one widget owns and renders it. When several distant parts of the app need the same changing value, examine Flutter’s shared-state approaches instead of moving every value into a single large State object.
Keep local state close to the widget that renders it
Use setState for a value whose owner and visible effect fit within one widget subtree. Keep the callback small, then verify the widget reads the updated field.
For a useful next check, run the Flutter version command in your project environment. The command below returned the recorded shell error on this server because Flutter is not installed here.
flutter --version
/usr/bin/bash: line 5: flutter: command not found
After Flutter is available, compare the field’s State owner with the widget that displays it when a lifecycle error appears. The setState API documentation explains the callback and lifecycle rules.
Frequently asked questions
These answers cover the boundary between a local setState update and state shared across an app.
Does setState reload the whole Flutter app?
No. It notifies Flutter that the State object’s widget subtree may need rebuilding. It does not reload the whole app.
Can the setState callback be async?
No. The callback runs synchronously and must not return a Future. Await work outside the callback, then update the field inside a synchronous setState callback.
When should I use something beyond setState?
Consider another state-management approach when state must be shared across distant parts of the app, persisted, or coordinated beyond one widget’s local UI.




