FlutterFlow has three state levels: App State persists globally across the entire app, Page State exists only on the current screen and resets when you navigate away, and Component State is scoped to a single reusable widget instance. For server data, Backend Queries on Firestore with real-time streaming keep UI synchronized automatically without manual state updates.
Understanding FlutterFlow's Three Layers of State
Every interactive app needs to remember things: is the user logged in, what tab is selected, what items are in the cart. FlutterFlow organizes this memory into three layers. Getting the layer right for each piece of data is the single most important architectural decision in a FlutterFlow app. The wrong layer causes data to unexpectedly disappear, persist when it should not, or trigger unnecessary rebuilds that slow the app down.
Prerequisites
- A FlutterFlow project with at least one page created
- Basic understanding of FlutterFlow's widget canvas and properties panel
- Optional: Firebase project connected for Backend Query examples
Step-by-step guide
Create App State Variables for Global Data
Create App State Variables for Global Data
App State variables are available everywhere in your app and survive page navigation. They are the right choice for data that multiple pages need — the logged-in user's name, a shopping cart item count, a selected theme, or a notification badge count. To create one: click the State Management icon in the left sidebar (looks like a circle with an arrow). Under 'App State', click '+'. Name your variable (e.g., 'cartItemCount'), set the type (Integer), and choose an initial value (0). Tick 'Persist State' if you want this value to survive app restarts (it is saved to local device storage). Leave 'Persist State' OFF for session-only data like selected tab index.
Expected result: The App State panel shows your new variable with its type and initial value. It is now accessible in every page and component's Expression Editor.
Create Page State Variables for Screen-Specific Data
Create Page State Variables for Screen-Specific Data
Page State variables live only on a single page and are destroyed when the user navigates away. Use them for things that belong to one screen: whether a password field is visible, a search query string, a selected filter chip, a currently expanded accordion item. To create Page State: select the page root widget in the widget tree (the top-level container). In the right Properties panel, scroll down to find the 'Page State' section and click '+'. Name the variable (e.g., 'isPasswordVisible'), set the type (Boolean), and enter an initial value (false). Page State variables appear in the Expression Editor only when you are working on that page.
Expected result: The selected page shows a Page State section in its properties with the new variable listed. Widgets on that page can now bind to it.
Bind a Widget Property to a State Variable
Bind a Widget Property to a State Variable
Now connect a widget's property to your state variable. Select a Text widget on the canvas. In the Properties panel, find the 'Value' field. Click the orange binding icon (looks like a chain link or lightning bolt) to the right of the field. This opens the Expression Editor. Navigate to App State → cartItemCount. The Text widget will now display the current value of cartItemCount. For a conditional binding (e.g., show/hide a widget based on a boolean), select the widget and go to Conditions in the properties panel. Set 'Visible' to a condition that reads 'If [Page State → isPasswordVisible] is false'. The widget instantly disappears or appears as the state changes.
Expected result: The Text widget shows the live value of cartItemCount. When you update cartItemCount in the Action Flow, the widget rebuilds automatically.
Update State from an Action Flow
Update State from an Action Flow
Select a Button widget. In the Actions tab, click '+' to add an action. In the Action palette, search for 'Update App State' or 'Update Page State'. Select the variable you want to modify (e.g., cartItemCount). Choose the update type: 'Set Value' (overwrite), 'Increment' (add a number), or for lists: 'Add Item' or 'Remove Item'. For cartItemCount, select 'Increment' and enter 1. Every widget bound to cartItemCount will rebuild immediately when the button is tapped. You can chain multiple state updates in one Action Flow — for example: increment cart count, set a 'lastAddedItem' string to the product name, and show a Snackbar confirmation.
Expected result: Tapping the button increments the cart count and the Text widget bound to cartItemCount updates instantly without a page refresh.
Use Component State for Reusable Widget Instances
Use Component State for Reusable Widget Instances
When you create a reusable Component (left sidebar → Components → '+'), it can have its own state. Component State is per-instance — if you place the same Component on a page three times, each instance has independent state. Example: an expandable FAQ card component has an 'isExpanded' boolean Component State. Tapping one card expands only that card, not all three. To add Component State: open the Component in the Component Editor, select the root widget, scroll to Component State in properties, and click '+'. Update Component State using 'Update Component State' in the Action Flow, just like Page State. This pattern is essential for lists, cards, and any repeated interactive element.
Expected result: Three instances of the FAQ card component on a page each expand and collapse independently without affecting each other.
Sync with Firestore Using Real-Time Backend Queries
Sync with Firestore Using Real-Time Backend Queries
For data that comes from your database, use Backend Queries instead of manually loading data into state variables. Select the page root widget (or a specific container). In Properties, scroll to Backend Query and click '+'. Choose Firestore Collection as the source. Select your collection (e.g., 'orders'). Under Query Type, choose 'Stream of Documents' (not 'Future', which is a one-time read). Under Filters, add a condition: 'userId == [Authenticated User → User Reference]'. Now bind a Repeating Group widget's source to this query. Every time Firestore data changes, the Repeating Group updates automatically — no polling, no manual state management, no page refresh needed.
Expected result: The Repeating Group shows live data from Firestore. When you add a document to the collection in Firebase Console, the widget updates on screen within 1-2 seconds without any action.
Complete working example
1// ============================================================2// FlutterFlow State Management — Custom Action Examples3// ============================================================4// These Custom Actions demonstrate state manipulation patterns5// that go beyond what the visual Action Flow editor supports.67// Example 1: Batch update multiple App State variables atomically8// Custom Action: resetCartState9Future<void> resetCartState() async {10 // In FlutterFlow, FFAppState() is the auto-generated App State class11 FFAppState().update(() {12 FFAppState().cartItemCount = 0;13 FFAppState().cartTotal = 0.0;14 FFAppState().cartItems = [];15 FFAppState().lastAddedItem = '';16 });17}1819// Example 2: Toggle a boolean App State variable20// Custom Action: toggleDarkMode21Future<void> toggleDarkMode() async {22 FFAppState().update(() {23 FFAppState().isDarkMode = !FFAppState().isDarkMode;24 });25}2627// Example 3: Add item to a list in App State if not already present28// Custom Action: addToFavorites (argument: itemId String)29Future<bool> addToFavorites(String itemId) async {30 final favorites = List<String>.from(FFAppState().favoriteIds);31 if (favorites.contains(itemId)) {32 return false; // Already in favorites33 }34 FFAppState().update(() {35 FFAppState().favoriteIds = [...favorites, itemId];36 });37 return true;38}3940// Example 4: Read a Page State variable in a Custom Action41// Note: Page State is passed as a parameter, not accessed directly42// Custom Action: validateSearchQuery (argument: query String)43String validateSearchQuery(String query) {44 final trimmed = query.trim();45 if (trimmed.isEmpty) return '';46 if (trimmed.length < 3) return '';47 // Return cleaned query to set back into Page State48 return trimmed.toLowerCase();49}5051// Note: Firestore real-time streams are configured visually in52// FlutterFlow's Backend Query panel — no custom code needed for53// basic real-time sync. Custom code is only needed for54// complex state logic like the examples above.Common mistakes
Why it's a problem: Storing large datasets (100+ items) in App State with persistence enabled
How to avoid: Store only lightweight identifiers (IDs, simple strings, counts, booleans) in App State. Load full object data on-demand from Firestore using Backend Queries. If you need a local cache, use a non-persisted App State list of IDs and query Firestore for details when displaying them.
Why it's a problem: Using App State where Page State is appropriate, causing unexpected data persistence
How to avoid: Use Page State for all data that should reset when the user leaves a screen — form fields, search queries, filter selections, expanded/collapsed states. Only promote data to App State if it genuinely needs to survive navigation.
Why it's a problem: Triggering a Backend Query with Single Time Query on data that changes in real time
How to avoid: Set the Backend Query to use a real-time stream (Single Time Query off). This uses Firestore's onSnapshot listener and automatically pushes updates to the widget when the underlying data changes.
Why it's a problem: Nesting Backend Queries inside a Repeating Group that itself has a Backend Query
How to avoid: Denormalize data in Firestore to include the nested data inside the parent document, or use a single query that fetches all needed data in one request. Alternatively, use a Custom Action to batch-fetch related documents.
Best practices
- Decide on state level before building a feature: write down whether the data is global (App State), page-scoped (Page State), or widget-scoped (Component State) before adding any variables.
- Use descriptive variable names that include their type or purpose: 'isLoadingProducts' instead of 'loading', 'selectedCategoryId' instead of 'selectedId'.
- Keep App State lean — aim for fewer than 20 variables. If your App State list grows beyond 20, audit whether some variables should be Page State or fetched fresh from Firestore instead.
- Set initial values for all state variables — never leave them as null unless nullable is explicitly intended and your UI handles the null case.
- For App State lists, use typed lists (List of DocumentReference, List of String) rather than List of Dynamic to catch type errors early in the Expression Editor.
- Use Conditional Visibility driven by state rather than conditionally building different pages — it is faster and avoids navigation stack complexity.
- Pair real-time Backend Queries with loading state variables: set 'isLoading' to true before the query and false when it resolves, then show a loading spinner while isLoading is true.
- Document each App State variable with a comment in the variable name or description field — future-you will thank present-you for knowing what 'flag2' means.
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I'm building a FlutterFlow e-commerce app. Explain when I should use App State, Page State, and Component State for the following data: shopping cart items, the search query on the search page, whether a product card's 'more info' section is expanded, the logged-in user's display name, and the selected tab on the main navigation bar.
In FlutterFlow, I have a product list page with a search bar and a filter chip row. What state variables do I need, what type and scope should each be, and how should I wire the search bar's onChange and the filter chip's onTap to update the Backend Query that powers the product Repeating Group?
Frequently asked questions
What is the difference between App State and Page State in FlutterFlow?
App State is global — available on every page and persists across navigation. Page State is local to one screen and is destroyed when the user leaves. Use App State for data multiple pages share (cart, user preferences). Use Page State for data that belongs to one screen (form inputs, filter selections, UI toggle states).
Does persisted App State survive when the user closes and reopens the app?
Yes, if you enable 'Persist State' on the variable, its value is saved to the device's local storage and restored when the app restarts. Variables without 'Persist State' reset to their initial value on every app launch.
Can I share state between a Component and the page it is placed on?
Component State is only accessible inside the component. To pass data from a component to the parent page, use a Callback Action — define an action parameter on the component and the parent page provides the actual action (e.g., Update App State) when configuring the component instance. To pass data into a component from the page, use Component Parameters.
When should I use a Backend Query instead of storing data in App State?
Use a Backend Query for any data that lives in Firestore — product lists, user profiles, orders, messages. Use App State only for UI state and lightweight user preferences. Never copy Firestore data into App State just to display it — a Backend Query bound directly to a widget is more efficient and stays in sync automatically.
What happens to Page State when the user uses the back button?
Page State is destroyed when the page is popped from the navigation stack. If the user navigates back and then forward again, Page State resets to initial values. This is intentional — if you need data to survive the back navigation, store it in App State before leaving the page.
Can I access App State inside a Custom Action?
Yes. FlutterFlow generates an FFAppState singleton class accessible in all Custom Actions. Read a value with FFAppState().myVariable and update it with FFAppState().update(() { FFAppState().myVariable = newValue; }). The update() call triggers a rebuild of all widgets bound to the changed variable.
Why does my widget not update when I change an App State variable?
The most common cause is updating App State outside of the update() callback in Custom Actions — writing FFAppState().cartCount++ without wrapping it in FFAppState().update(() {...}) does not trigger a rebuild. In the visual Action Flow editor, using 'Update App State' actions always triggers rebuilds correctly.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation