A Reflex-Inspired State Management Pattern for Flet's Declarative UI

[iBuitron]

Overview

This document presents an alternative approach to structuring Flet declarative applications, inspired by the Reflex framework. The key principle is separation of concerns: keeping your domain models clean and framework-agnostic while managing UI state in dedicated observable classes.

Core Principles

1. Domain Models Stay Pure

Your business logic and data models should be independent of the UI framework. Use Pydantic's BaseModel (or any other approach) for models that represent your actual data.

from pydantic import BaseModel

class User(BaseModel):
    """Pure domain model - framework agnostic"""
    first_name: str
    last_name: str

2. State Classes Handle Reactivity

Create @ft.observable state classes that wrap your domain models and contain all UI logic and event handlers.

@ft.observable
@dataclass
class UserState:
    """Reactive state wrapper for User"""
    user: User
    is_editing: bool = False
    temp_first_name: str = ""
    temp_last_name: str = ""
    
    # All event handlers live here
    def start_edit(self):
        self.temp_first_name = self.user.first_name
        self.temp_last_name = self.user.last_name
        self.is_editing = True

3. Components Are Pure Presentation

Components receive state objects and render UI based on them. They contain no business logic - only presentation and delegation to state event handlers.

@ft.component
def UserView(user_state: UserState, app_state: AppState) -> ft.Control:
    """Pure presentation component"""
    if not user_state.is_editing:
        return ft.Row([
            ft.Text(f"{user_state.first_name} {user_state.last_name}"),
            ft.Button("Edit", on_click=lambda _: app_state.start_edit_user(user_state)),
        ])
    # ... editing view

Complete Example: User Management CRUD

https://docs.flet.dev/cookbook/declarative-vs-imperative-crud-app/#example-2-declarative

Step 1: Domain Model

from pydantic import BaseModel

class User(BaseModel):
    """Domain model - can be used with databases, APIs, etc."""
    first_name: str
    last_name: str

Step 2: State Classes

from dataclasses import dataclass, field
import flet as ft

@ft.observable
@dataclass
class UserState:
    """State for individual user with editing logic"""
    user: User
    # Local editing state
    is_editing: bool = False
    temp_first_name: str = ""
    temp_last_name: str = ""

    @property
    def first_name(self) -> str:
        return self.user.first_name

    @property
    def last_name(self) -> str:
        return self.user.last_name

    # Event handlers for user-level operations
    def start_edit(self):
        """Initialize editing mode"""
        self.temp_first_name = self.user.first_name
        self.temp_last_name = self.user.last_name
        self.is_editing = True

    def save(self):
        """Save changes to the domain model"""
        self.user.first_name = self.temp_first_name
        self.user.last_name = self.temp_last_name
        self.is_editing = False

    def cancel(self):
        """Cancel editing without saving"""
        self.is_editing = False

    def update_temp_first_name(self, value: str):
        self.temp_first_name = value

    def update_temp_last_name(self, value: str):
        self.temp_last_name = value


@ft.observable
@dataclass
class AppState:
    """Application-level state managing the collection"""
    users: list[UserState] = field(default_factory=list)
    # Form fields
    new_first_name: str = ""
    new_last_name: str = ""

    # Event handlers for collection operations
    def add_user(self):
        """Add a new user to the collection"""
        if self.new_first_name.strip() or self.new_last_name.strip():
            user = User(first_name=self.new_first_name, last_name=self.new_last_name)
            user_state = UserState(user=user)
            self.users.append(user_state)
            # Clear form
            self.new_first_name = ""
            self.new_last_name = ""

    def delete_user(self, user_state: UserState):
        """Remove a user from the collection"""
        self.users.remove(user_state)

    def start_edit_user(self, user_state: UserState):
        """Coordinate starting edit for a specific user"""
        user_state.start_edit()

    def save_user(self, user_state: UserState):
        """Coordinate saving a specific user"""
        user_state.save()

    def cancel_edit_user(self, user_state: UserState):
        """Coordinate canceling edit for a specific user"""
        user_state.cancel()

    def update_new_first_name(self, value: str):
        self.new_first_name = value

    def update_new_last_name(self, value: str):
        self.new_last_name = value

Step 3: Components (Pure Presentation)

@ft.component
def UserView(user_state: UserState, app_state: AppState) -> ft.Control:
    """
    Displays a single user - read-only or editing mode.
    All logic is delegated to state event handlers.
    """
    if not user_state.is_editing:
        return ft.Row([
            ft.Text(f"{user_state.first_name} {user_state.last_name}"),
            ft.Button("Edit", on_click=lambda _: app_state.start_edit_user(user_state)),
            ft.Button("Delete", on_click=lambda _: app_state.delete_user(user_state)),
        ])

    return ft.Row([
        ft.TextField(
            label="First Name",
            value=user_state.temp_first_name,
            on_change=lambda e: user_state.update_temp_first_name(e.control.value),
            width=180,
        ),
        ft.TextField(
            label="Last Name",
            value=user_state.temp_last_name,
            on_change=lambda e: user_state.update_temp_last_name(e.control.value),
            width=180,
        ),
        ft.Button("Save", on_click=lambda _: app_state.save_user(user_state)),
        ft.Button("Cancel", on_click=lambda _: app_state.cancel_edit_user(user_state)),
    ])


@ft.component
def AddUserForm(app_state: AppState) -> ft.Control:
    """Form to add new users - delegates all logic to AppState"""
    return ft.Row([
        ft.TextField(
            label="First Name",
            width=200,
            value=app_state.new_first_name,
            on_change=lambda e: app_state.update_new_first_name(e.control.value),
        ),
        ft.TextField(
            label="Last Name",
            width=200,
            value=app_state.new_last_name,
            on_change=lambda e: app_state.update_new_last_name(e.control.value),
        ),
        ft.Button("Add", on_click=lambda _: app_state.add_user()),
    ])


@ft.component
def UserNameText(user_state: UserState) -> ft.Control:
    """Simple component to display user name"""
    return ft.Text(f"{user_state.first_name} {user_state.last_name}")


@ft.component
def UserNameRow(users: list[UserState]) -> ft.Control:
    """Display all user names in a row"""
    return ft.Row(
        [UserNameText(user_state) for user_state in users],
        spacing=50,
    )


@ft.component
def AppView() -> list[ft.Control]:
    """Root component - initializes state and composes the UI"""
    app_state, _ = ft.use_state(
        AppState(
            users=[
                UserState(user=User(first_name="John", last_name="Doe")),
                UserState(user=User(first_name="Jane", last_name="Doe")),
                UserState(user=User(first_name="Foo", last_name="Bar")),
            ]
        )
    )

    return [
        AddUserForm(app_state),
        UserNameRow(app_state.users),
        *[UserView(user_state, app_state) for user_state in app_state.users],
    ]


ft.run(lambda page: page.render(AppView))

Key Differences from the Official Examples

1. No Hooks for Business Logic

Official example uses use_state for editing state:

# Official approach
@ft.component
def UserView(user: User, delete_user):
    is_editing, set_is_editing = ft.use_state(False)  # Hook
    # ...

Our approach moves this to the state class:

# Reflex-inspired approach
@ft.observable
@dataclass
class UserState:
    is_editing: bool = False  # Part of observable state
    # ...

2. No Functions Passed as Props

Official example passes functions between components:

# Official approach
AddUserForm(app.add_user)  # Passing function
UserView(user, app.delete_user)  # Passing function

Our approach passes state objects:

# Reflex-inspired approach
AddUserForm(app_state)  # Pass entire state
UserView(user_state, app_state)  # Pass states, not functions

3. Domain Model Separation

Official example makes the domain model observable:

# Official approach
@ft.observable
@dataclass
class User:  # Domain model is observable
    first_name: str

Our approach keeps them separate:

# Reflex-inspired approach
class User(BaseModel):  # Pure domain model
    first_name: str

@ft.observable
@dataclass
class UserState:  # Separate observable state
    user: User

Critical Rule: Pass Observable Objects, Not Properties

❌ This WILL NOT work: (It doesn't work in the original version either because it expects @observable to be passed)

@ft.component
def UserNameBroken(first_name: str, last_name: str):
    return ft.Text(f"{first_name} {last_name}")
# Usage - passes VALUES, not OBSERVABLES
UserNameBroken(user_state.first_name, user_state.last_name)
# This component will NOT re-render when the user changes!

✅ This WILL work:

@ft.component
def UserName(user_state: UserState):
    return ft.Text(f"{user_state.first_name} {user_state.last_name}")
# Usage - passes OBSERVABLE OBJECT
UserName(user_state)

# This component WILL re-render when user_state changes!

Why? When you pass user_state.first_name, you're passing the string value at that moment in time (e.g., "John"). The component has no connection to the observable. When you pass user_state, you pass a reference to the observable object, so Flet can detect changes and trigger re-renders.

Benefits of This Pattern

1. Testability

Your domain models can be tested without any UI framework:

def test_user_creation():
    user = User(first_name="John", last_name="Doe")
    assert user.first_name == "John"
    # No Flet required!

2. Reusability

The same User model can be used in:

• Database operations (SQLAlchemy, etc.)
• API serialization
• Backend services
• Other UI frameworks

3. Clear Separation of Concerns

• Domain models: Business data and rules
• State classes: UI state and event handlers
• Components: Pure presentation

4. Easier to Reason About

All state mutations happen in one place (state classes), not scattered across components.

5. Scalable

As your app grows, you add more state classes and compose them, rather than nesting hooks and callbacks.

Comparison with Reflex

This pattern closely mirrors Reflex's architecture:

# Reflex example
class UserState(rx.State):
    first_name: str
    last_name: str
    
    def update_name(self, name: str):
        self.first_name = name

# Flet equivalent
@ft.observable
@dataclass
class UserState:
    first_name: str
    last_name: str
    
    def update_name(self, name: str):
        self.first_name = name

Both frameworks follow the principle: State classes own the data and logic, components own the presentation.

When to Use This Pattern

Use this pattern when:

• Building medium to large applications
• You need to separate domain logic from UI
• You want testable business logic
• You're familiar with Reflex or similar frameworks
• You prefer explicit state management

The official pattern might be better when:

• Building small, simple apps
• You want minimal boilerplate
• You're coming from React and prefer hooks everywhere
• Your domain model is simple and UI-specific

Conclusion

This Reflex-inspired pattern offers a clean, scalable way to structure Flet applications by:

• Keeping domain models framework-agnostic
• Centralizing UI logic in observable state classes
• Making components pure presentation layers

The result is code that's easier to test, maintain, and scale as your application grows.

[iBuitron]

Another aproach, instead passing arguments:

from dataclasses import dataclass, field
from typing import Any, Optional, Type, TypeVar

import flet as ft
from pydantic import BaseModel

T = TypeVar("T")


# ============================================
# State Manager - Simulates Reflex's get_state
# ============================================


class StateManager:
    """Global state registry - simulates Reflex's StateManager"""

    _registry: dict[Type, Any] = {}

    @classmethod
    def register_state(cls, state_type: Type[T], instance: T):
        """Register a state instance"""
        cls._registry[state_type] = instance

    @classmethod
    def init_state(cls, state_instance: T) -> T:
        """
        Initialize and register a state in one step.
        Use this in the root component to set up states.

        Usage:
            @ft.component
            def AppView():
                StateManager.init_state(GlobalState())
                StateManager.init_state(AppState(users=[...]))
                return [...]
        """
        state_type = type(state_instance)
        state, _ = ft.use_state(state_instance)
        cls._registry[state_type] = state
        return state

    @classmethod
    def get_state(cls, state_type: Type[T]) -> Optional[T]:
        """
        Get a state instance - similar to Reflex's get_state.
        Use this inside observable class methods.
        """
        return cls._registry.get(state_type)

    @classmethod
    def use_state(cls, state_type: Type[T]) -> T:
        """
        Hook to access global state with auto-updates.
        Use this inside @ft.component functions.

        Usage:
            @ft.component
            def MyComponent():
                global_state = StateManager.use_state(GlobalState)
                return ft.Text(f"Counter: {global_state.counter}")
        """
        state = cls._registry.get(state_type)

        if state is None:
            raise ValueError(
                f"State {state_type.__name__} not registered in StateManager"
            )

        # Create subscription so component re-renders when state changes
        _, _ = ft.use_state(state)

        return state


# ============================================
# Domain Model
# ============================================


class User(BaseModel):
    """Domain model - framework agnostic"""

    first_name: str
    last_name: str


# ============================================
# Counter State
# ============================================


@ft.observable
@dataclass
class CounterState:
    """Counter application metrics"""

    counter: int = 0

    def increment(self):
        self.counter += 1

    def decrement(self):
        self.counter -= 1


# ============================================
# User State
# ============================================


@ft.observable
@dataclass
class UserState:
    """State for individual user with editing logic"""

    user: User
    is_editing: bool = False
    temp_first_name: str = ""
    temp_last_name: str = ""

    @property
    def first_name(self) -> str:
        return self.user.first_name

    @property
    def last_name(self) -> str:
        return self.user.last_name

    def start_edit(self):
        self.temp_first_name = self.user.first_name
        self.temp_last_name = self.user.last_name
        self.is_editing = True

    def save(self):
        self.user.first_name = self.temp_first_name
        self.user.last_name = self.temp_last_name
        self.is_editing = False

    def cancel(self):
        self.is_editing = False

    def update_temp_first_name(self, value: str):
        self.temp_first_name = value

    def update_temp_last_name(self, value: str):
        self.temp_last_name = value


# ============================================
# App State
# ============================================


@ft.observable
@dataclass
class AppState:
    """Application-level state managing users"""

    users: list[UserState] = field(default_factory=list)
    new_first_name: str = ""
    new_last_name: str = ""

    def add_user(self):
        """Add user and update global counter"""
        if self.new_first_name.strip() or self.new_last_name.strip():
            user = User(first_name=self.new_first_name, last_name=self.new_last_name)
            user_state = UserState(user=user)
            self.users.append(user_state)
            self.new_first_name = ""
            self.new_last_name = ""

            # ✅ Get state in class methods - like Reflex
            global_state = StateManager.get_state(CounterState)
            if global_state:
                global_state.increment()

    def delete_user(self, user_state: UserState):
        """Delete user and update global counter"""
        self.users.remove(user_state)

        global_state = StateManager.get_state(CounterState)
        if global_state:
            global_state.decrement()

    def start_edit_user(self, user_state: UserState):
        user_state.start_edit()

    def save_user(self, user_state: UserState):
        user_state.save()

    def cancel_edit_user(self, user_state: UserState):
        user_state.cancel()

    def update_new_first_name(self, value: str):
        self.new_first_name = value

    def update_new_last_name(self, value: str):
        self.new_last_name = value


# ============================================
# Components
# ============================================


@ft.component
def GlobalCounter() -> ft.Control:
    """Display global counter - gets state from StateManager"""
    # ✅ Use StateManager.use_state in components
    counter_state = StateManager.use_state(CounterState)
    return ft.Text(f"Total users (adds): {counter_state.counter}", size=20)


@ft.component
def UserView(user_state: UserState) -> ft.Control:
    """Displays a single user"""
    # ✅ Get app_state from StateManager
    app_state = StateManager.use_state(AppState)

    if not user_state.is_editing:
        return ft.Row(
            [
                ft.Text(f"{user_state.first_name} {user_state.last_name}"),
                ft.Button(
                    "Edit", on_click=lambda _: app_state.start_edit_user(user_state)
                ),
                ft.Button(
                    "Delete", on_click=lambda _: app_state.delete_user(user_state)
                ),
            ]
        )

    return ft.Row(
        [
            ft.TextField(
                label="First Name",
                value=user_state.temp_first_name,
                on_change=lambda e: user_state.update_temp_first_name(e.control.value),
                width=180,
            ),
            ft.TextField(
                label="Last Name",
                value=user_state.temp_last_name,
                on_change=lambda e: user_state.update_temp_last_name(e.control.value),
                width=180,
            ),
            ft.Button("Save", on_click=lambda _: app_state.save_user(user_state)),
            ft.Button(
                "Cancel", on_click=lambda _: app_state.cancel_edit_user(user_state)
            ),
        ]
    )


@ft.component
def AddUserForm() -> ft.Control:
    """Form to add users - gets state from StateManager"""
    # ✅ Use StateManager.use_state
    app_state = StateManager.use_state(AppState)

    return ft.Row(
        [
            ft.TextField(
                label="First Name",
                width=200,
                value=app_state.new_first_name,
                on_change=lambda e: app_state.update_new_first_name(e.control.value),
            ),
            ft.TextField(
                label="Last Name",
                width=200,
                value=app_state.new_last_name,
                on_change=lambda e: app_state.update_new_last_name(e.control.value),
            ),
            ft.Button("Add", on_click=lambda _: app_state.add_user()),
        ]
    )


@ft.component
def UserNameText(user_state: UserState) -> ft.Control:
    """Simple component to display user name"""
    return ft.Text(f"{user_state.first_name} {user_state.last_name}")


@ft.component
def UserNameRow() -> ft.Control:
    """Display all user names in a row"""
    # ✅ Get state from StateManager
    app_state = StateManager.use_state(AppState)

    return ft.Row(
        [UserNameText(user_state) for user_state in app_state.users],
        spacing=50,
    )


@ft.component
def AppView() -> list[ft.Control]:
    """Root component - initializes and registers states"""

    # ✅ Initialize and register states in one line each
    StateManager.init_state(CounterState())
    StateManager.init_state(
        AppState(
            users=[
                UserState(user=User(first_name="John", last_name="Doe")),
                UserState(user=User(first_name="Jane", last_name="Doe")),
                UserState(user=User(first_name="Foo", last_name="Bar")),
            ]
        )
    )

    return [
        GlobalCounter(),
        AddUserForm(),
        UserNameRow(),
        *[
            UserView(user_state)
            for user_state in StateManager.use_state(AppState).users
        ],
    ]


ft.run(lambda page: page.render(AppView))

[iBuitron]

Enhanced State Management Pattern for Flet: Auto-Registration & Session Isolation

Update to Previous Discussion

This is an evolution of the Reflex-Inspired State Management Pattern, addressing key limitations and proposing integration into Flet's core to eliminate boilerplate and improve developer experience.

🎯 Problem Statement

The current approach requires manual state initialization in every root component:

@ft.component
def AppView():
    # ❌ Manual registration required for each state
    StateManager.init_state(CounterState())
    StateManager.init_state(AppState())
    # ... rest of component

Issues:

1. Boilerplate: Every app needs the same initialization code
2. Error-prone: Easy to forget registering a state
3. Session isolation missing: Current implementation uses a global dictionary, breaking multi-user scenarios
4. Not scalable: As apps grow, initialization code becomes unwieldy

✨ Proposed Solution: Auto-Registration + Session Isolation

Key Improvements

1. Automatic State Discovery via __init_subclass__

States register themselves when defined, eliminating manual registration:

# ✅ Just inherit from State - auto-registers!
@ft.observable
@dataclass
class AppState(State):
    count: int = 0

2. Session-Scoped State Storage

Uses page.session.store instead of global dictionary for proper multi-user isolation:

# Each user session gets independent state instances
session.store.set(storage_key, instance)

3. Zero-Boilerplate Initialization

Integration with page.render() eliminates manual init_all() calls:

# ✅ No initialization needed - happens automatically!
@ft.component
def AppView():
    app_state = State.use(AppState)
    return [...]

ft.run(lambda page: page.render(AppView))

📋 Complete Implementation

Core Infrastructure

from dataclasses import dataclass, field
from typing import Any, Optional, Type, TypeVar, ClassVar
import flet as ft
from pydantic import BaseModel

T = TypeVar("T")


class StateRegistry:
    """
    Internal registry for state classes and instances.
    Handles the infrastructure of state management - NOT meant to be inherited.
    
    Architecture:
    - Class-level: Tracks all State subclasses (singleton, app-wide)
    - Instance-level: Stores state instances per session (isolated)
    """
    
    STATE_KEY_PREFIX = "_state_manager_"
    
    # Class registry: shared across all sessions
    _registered_state_classes: ClassVar[set[Type["State"]]] = set()

    @classmethod
    def _get_session(cls):
        """Get current session from Flet context"""
        return ft.context.page.session

    @classmethod
    def _get_storage_key(cls, state_type: Type[T]) -> str:
        """Generate unique storage key for state type"""
        return f"{cls.STATE_KEY_PREFIX}{state_type.__name__}"

    @classmethod
    def register_class(cls, state_class: Type["State"]):
        """
        Register a state class for auto-initialization.
        Called automatically via __init_subclass__.
        """
        cls._registered_state_classes.add(state_class)

    @classmethod
    def register_instance(cls, state_type: Type[T], instance: T):
        """
        Register a state instance in current session storage.
        Ensures session isolation - each user gets their own instances.
        """
        session = cls._get_session()
        storage_key = cls._get_storage_key(state_type)
        session.store.set(storage_key, instance)

    @classmethod
    def get_instance(cls, state_type: Type[T]) -> Optional[T]:
        """
        Retrieve state instance from current session storage.
        Returns None if not yet initialized (before init_all).
        """
        try:
            session = cls._get_session()
            storage_key = cls._get_storage_key(state_type)
            return session.store.get(storage_key)
        except RuntimeError:
            # Context not available (e.g., outside component render)
            return None

    @classmethod
    def init_all(cls):
        """
        Initialize all registered state classes for current session.
        
        Called automatically by page.render() in proposed integration.
        Creates one instance per state class per session.
        
        Returns:
            Dict mapping state class names to their instances
        """
        initialized_states = {}
        
        for state_class in cls._registered_state_classes:
            # Create fresh instance for this session
            instance = state_class()
            
            # Use ft.use_state hook for reactivity
            state, _ = ft.use_state(instance)
            
            # Store in session-scoped storage
            cls.register_instance(state_class, state)
            
            initialized_states[state_class.__name__] = state
        
        return initialized_states


class State:
    """
    Base class for all global application states.
    
    Key Features:
    - Auto-registration: Subclasses register themselves automatically
    - Session isolation: Each user session gets independent state instances
    - Type-safe: Full type inference with generics
    - Clean API: Simple use() and get() methods
    
    Usage Pattern:
        # 1. Define your state (auto-registers)
        @ft.observable
        @dataclass
        class AppState(State):
            count: int = 0
            
            def increment(self):
                self.count += 1
        
        # 2. Use in components (with reactivity)
        @ft.component
        def Counter():
            app_state = State.use(AppState)
            return ft.Text(f"Count: {app_state.count}")
        
        # 3. Access in state methods (without reactivity)
        @ft.observable
        @dataclass
        class CartState(State):
            def checkout(self):
                user = State.get(UserState)  # Access other states
                # ... checkout logic
    
    Architecture Benefits:
    - Separation of concerns: State (domain) vs StateRegistry (infrastructure)
    - Similar to Django: inherit from Model, not from QuerySet
    - Similar to Reflex: inherit from rx.State, not from StateManager
    """
    
    def __init_subclass__(cls, **kwargs):
        """
        Magic method called automatically when a class inherits from State.
        
        This is the auto-registration mechanism:
        When Python reads "class AppState(State):", this method runs
        and registers AppState in the StateRegistry.
        
        No decorators or explicit calls needed!
        """
        super().__init_subclass__(**kwargs)
        StateRegistry.register_class(cls)
    
    @classmethod
    def use(cls, state_type: Type[T]) -> T:
        """
        Hook to access a registered state WITH reactivity.
        Use this inside @ft.component functions.
        
        The component will automatically re-render when the state changes.
        
        Example:
            @ft.component
            def MyComponent():
                app_state = State.use(AppState)
                return ft.Text(f"Count: {app_state.count}")
        
        Raises:
            ValueError: If state not initialized (init_all not called)
        """
        state = StateRegistry.get_instance(state_type)
        
        if state is None:
            raise ValueError(
                f"State {state_type.__name__} not registered. "
                f"Make sure State.init_all() was called (or page.render() in integrated version)."
            )
        
        # Subscribe to changes for reactivity
        _, _ = ft.use_state(state)
        
        return state
    
    @classmethod
    def get(cls, state_type: Type[T]) -> T:
        """
        Get a state instance WITHOUT subscribing to updates.
        Use this inside observable class methods or event handlers.
        
        This is for state-to-state communication without triggering re-renders.
        Safe to use after State.init_all() as all states are guaranteed to exist.
        
        Example:
            @ft.observable
            @dataclass
            class AppState(State):
                def add_user(self):
                    counter = State.get(CounterState)  # No re-render
                    counter.increment()
        
        Raises:
            RuntimeError: If state not initialized (init_all not called)
        
        Type Safety:
            Returns the exact type requested, not Optional[T],
            because after init_all() all registered states exist.
        """
        state = StateRegistry.get_instance(state_type)
        
        if state is None:
            raise RuntimeError(
                f"State {state_type.__name__} not initialized. "
                f"Make sure State.init_all() was called in your root component."
            )
        
        return state
    
    @classmethod
    def init_all(cls):
        """
        Initialize all registered states for current session.
        
        In standalone usage: Call once in root component.
        In integrated version: Called automatically by page.render().
        
        Example (standalone):
            @ft.component
            def App(page: ft.Page):
                State.init_all()  # Initialize all states
                return [...]
        
        Example (integrated - proposed):
            @ft.component
            def App(page: ft.Page):
                # init_all() happens automatically in page.render()!
                return [...]
        """
        return StateRegistry.init_all()

Example Application

# ============================================================================
# DOMAIN MODELS (Framework-agnostic)
# ============================================================================

class User(BaseModel):
    """Pure domain model - can be used with databases, APIs, etc."""
    first_name: str
    last_name: str


# ============================================================================
# OBSERVABLE MODELS (Not global states - multiple instances)
# ============================================================================

@ft.observable
@dataclass
class UserObs:
    """
    Observable wrapper for individual User with editing logic.
    
    Note: This is NOT a State subclass because we need multiple instances.
    It's an observable model that lives inside AppState.users list.
    """
    user: User
    is_editing: bool = False
    temp_first_name: str = ""
    temp_last_name: str = ""

    @property
    def first_name(self) -> str:
        return self.user.first_name

    @property
    def last_name(self) -> str:
        return self.user.last_name

    def start_edit(self):
        """Initialize editing mode"""
        self.temp_first_name = self.user.first_name
        self.temp_last_name = self.user.last_name
        self.is_editing = True

    def save(self):
        """Save changes to domain model"""
        self.user.first_name = self.temp_first_name
        self.user.last_name = self.temp_last_name
        self.is_editing = False

    def cancel(self):
        """Cancel editing without saving"""
        self.is_editing = False


# ============================================================================
# GLOBAL STATES (Auto-registered via State inheritance)
# ============================================================================

@ft.observable
@dataclass
class CounterState(State):
    """
    Global counter state - tracks total users across the app.
    
    Auto-registered when Python reads this class definition.
    Accessible via State.use(CounterState) in any component.
    """
    count: int = 0

    def increment(self):
        """Increment the counter"""
        self.count += 1

    def decrement(self):
        """Decrement the counter"""
        self.count -= 1


@ft.observable
@dataclass
class AppState(State):
    """
    Application-level state managing user collection.
    
    Demonstrates state-to-state communication:
    - add_user() updates CounterState via State.get()
    - No prop drilling needed
    - Type-safe access to other states
    """
    users: list[UserObs] = field(default_factory=list)
    new_first_name: str = ""
    new_last_name: str = ""

    def add_user(self):
        """Add a new user and update global counter"""
        if self.new_first_name.strip() or self.new_last_name.strip():
            # Create domain model
            user = User(
                first_name=self.new_first_name, 
                last_name=self.new_last_name
            )
            
            # Wrap in observable
            user_obs = UserObs(user=user)
            self.users.append(user_obs)

            # ✅ State-to-state communication (no prop drilling!)
            counter = State.get(CounterState)
            counter.increment()

            # Clear form
            self.new_first_name = ""
            self.new_last_name = ""

    def delete_user(self, user_obs: UserObs):
        """Remove a user and update global counter"""
        counter = State.get(CounterState)
        self.users.remove(user_obs)
        counter.decrement()


# ============================================================================
# COMPONENTS (Pure presentation)
# ============================================================================

@ft.component
def UserView(user_obs: UserObs) -> ft.Control:
    """
    Displays a single user - read-only or editing mode.
    
    Note how we access AppState via State.use() instead of prop drilling.
    Component automatically re-renders when AppState changes.
    """
    app_state = State.use(AppState)

    if not user_obs.is_editing:
        return ft.Row([
            ft.Text(f"{user_obs.first_name} {user_obs.last_name}"),
            ft.Button("Edit", on_click=lambda _: user_obs.start_edit()),
            ft.Button("Delete", on_click=lambda _: app_state.delete_user(user_obs)),
        ])

    return ft.Row([
        ft.TextField(
            label="First Name",
            value=user_obs.temp_first_name,
            on_change=lambda e: setattr(user_obs, "temp_first_name", e.control.value),
            width=180,
        ),
        ft.TextField(
            label="Last Name",
            value=user_obs.temp_last_name,
            on_change=lambda e: setattr(user_obs, "temp_last_name", e.control.value),
            width=180,
        ),
        ft.Button("Save", on_click=lambda _: user_obs.save()),
        ft.Button("Cancel", on_click=lambda _: user_obs.cancel()),
    ])


@ft.component
def AddUserForm() -> ft.Control:
    """
    Form to add new users.
    
    Accesses AppState directly - no need to pass it as a prop.
    """
    app_state = State.use(AppState)
    
    return ft.Row([
        ft.TextField(
            label="First Name",
            width=200,
            value=app_state.new_first_name,
            on_change=lambda e: setattr(app_state, "new_first_name", e.control.value),
        ),
        ft.TextField(
            label="Last Name",
            width=200,
            value=app_state.new_last_name,
            on_change=lambda e: setattr(app_state, "new_last_name", e.control.value),
        ),
        ft.Button("Add", on_click=app_state.add_user),
    ])


@ft.component
def UserNameRow() -> ft.Control:
    """Display all user names in a row"""
    users = State.use(AppState).users

    @ft.component
    def UserName(user_obs: UserObs) -> ft.Control:
        return ft.Text(f"{user_obs.first_name} {user_obs.last_name}")

    return ft.Row(
        [UserName(user_obs) for user_obs in users],
        spacing=50,
    )


@ft.component
def AppView(page: ft.Page) -> list[ft.Control]:
    """
    Root component.
    
    Current version: Requires manual State.init_all()
    Proposed integrated version: This would be automatic in page.render()
    """
    
    # ⚠️ Currently required - would be automatic with integration
    State.init_all()
    
    # ✅ Access states anywhere without prop drilling
    app_state = State.use(AppState)
    counter_state = State.use(CounterState)

    return [
        ft.Text(f"Session ID: {page.session.id}", size=12, color=ft.Colors.GREY),
        ft.Divider(),
        AddUserForm(),
        UserNameRow(),
        ft.Text(f"Total users: {counter_state.count}"),
        *[UserView(user_obs) for user_obs in app_state.users],
    ]


# ============================================================================
# RUN APP
# ============================================================================

ft.run(lambda page: page.render(lambda: AppView(page)))

Integration Point: page.render()

🔍 Technical Deep Dive

Why Session Storage?

# ❌ WRONG: Global dictionary (current approach in discussion)
class StateManager:
    _registry: dict[Type, Any] = {}  # Shared across ALL users!

# User A logs in
StateManager._registry[UserState] = UserState(name="Alice")

# User B logs in - OVERWRITES User A's state!
StateManager._registry[UserState] = UserState(name="Bob")

# ✅ CORRECT: Session-scoped storage
session.store.set(key, instance)  # Isolated per user session

Why Auto-Registration?

# Python calls __init_subclass__ automatically when class is defined
class AppState(State):  # ← Triggers __init_subclass__
    pass

# Equivalent to (but cleaner than):
class AppState:
    pass
StateManager.register_class(AppState)  # Manual registration

Why Separate State and StateRegistry?

Principle: Users inherit from what they ARE, not from what MANAGES them

# ✅ Semantic correctness
class AppState(State):        # AppState IS-A State
    pass

# ❌ Semantic confusion
class AppState(StateRegistry):  # AppState is NOT a Registry
    pass

Similar to:

• Django: class User(Model) not class User(QuerySet)
• SQLAlchemy: class User(Base) not class User(Session)
• Reflex: class AppState(rx.State) not class AppState(rx.StateManager)

🙋 Request for Feedback

This proposal aims to make Flet's state management:

• More ergonomic: Less boilerplate, clearer intent
• More robust: Session isolation prevents multi-user bugs
• More scalable: O(1) initialization regardless of state count
• More "Pythonic": Uses language features (__init_subclass__) naturally

Would love to hear thoughts from:

• @FeodorFitsner on feasibility of page.render() integration
• Community members who've built large Flet apps
• Anyone who's hit pain points with current state management

---

[iBuitron]

remove State.get_state(type) and State.use_state(type) to TypeState.use_state() and TypeState.get_state

from dataclasses import dataclass, field
from typing import Any, ClassVar, Optional, Type, TypeVar

import flet as ft
from pydantic import BaseModel

T = TypeVar("T")


class StateRegistry:
    """
    Internal registry for state classes and instances.
    This is the infrastructure layer - not meant to be inherited from.
    """

    STATE_KEY_PREFIX = "_state_manager_"
    _registered_state_classes: ClassVar[set[Type["State"]]] = set()

    @classmethod
    def _get_session(cls):
        """Get current session from context"""
        return ft.context.page.session

    @classmethod
    def _get_storage_key(cls, state_type: Type[T]) -> str:
        """Generate storage key for state type"""
        return f"{cls.STATE_KEY_PREFIX}{state_type.__name__}"

    @classmethod
    def register_class(cls, state_class: Type["State"]):
        """Register a state class for auto-initialization"""
        cls._registered_state_classes.add(state_class)

    @classmethod
    def register_instance(cls, state_type: Type[T], instance: T):
        """Register a state instance in current session"""
        session = cls._get_session()
        storage_key = cls._get_storage_key(state_type)
        session.store.set(storage_key, instance)

    @classmethod
    def get_instance(cls, state_type: Type[T]) -> Optional[T]:
        """Get a state instance from current session"""
        try:
            session = cls._get_session()
            storage_key = cls._get_storage_key(state_type)
            return session.store.get(storage_key)
        except RuntimeError:
            return None

    @classmethod
    def init_all(cls):
        """Initialize all registered state classes for current session"""
        initialized_states = {}
        for state_class in cls._registered_state_classes:
            instance = state_class()
            state, _ = ft.use_state(instance)
            cls.register_instance(state_class, state)
            initialized_states[state_class.__name__] = state
        return initialized_states


class State:
    """
    Base class for all global application states.

    Usage:
        @ft.observable
        @dataclass
        class AppState(State):
            count: int = 0

            def increment(self):
                self.count += 1

    The state will be automatically registered and available via:
        app_state = AppState.use()  # 🎯 Direct access!
    """

    def __init_subclass__(cls, **kwargs):
        """Auto-register when inherited"""
        super().__init_subclass__(**kwargs)
        StateRegistry.register_class(cls)

    @classmethod
    def use_state(cls: Type[T]) -> T:
        """
        Hook to access this state with auto-updates.
        Use this inside @ft.component functions.

        Example:
            @ft.component
            def MyComponent():
                app_state = AppState.use()  # 🎯 Direct!
                return ft.Text(f"Count: {app_state.count}")
        """
        state = StateRegistry.get_instance(cls)
        if state is None:
            raise ValueError(
                f"State {cls.__name__} not registered. "
                f"Did you call State.init_all() in your root component?"
            )
        _, _ = ft.use_state(state)
        return state

    @classmethod
    def get_state(cls: Type[T]) -> T:
        """
        Get this state instance without subscribing to updates.
        Use this inside observable class methods or event handlers.

        Example:
            def add_user(self):
                counter = CounterState.get()  # 🎯 Direct!
                counter.increment()

        Raises:
            RuntimeError: If state not initialized (init_all not called)
        """
        state = StateRegistry.get_instance(cls)
        if state is None:
            raise RuntimeError(
                f"State {cls.__name__} not initialized. "
                f"Make sure State.init_all() was called in your root component."
            )
        return state

    @classmethod
    def init_all(cls):
        """
        Initialize all registered states. Call once in root component.

        Example:
            @ft.component
            def App(page: ft.Page):
                State.init_all()
                return [...]
        """
        return StateRegistry.init_all()


# ============================================================================
# DOMAIN MODELS
# ============================================================================


class User(BaseModel):
    """Domain model - can be used with databases, APIs, etc."""

    first_name: str
    last_name: str


# ============================================================================
# OBSERVABLE MODELS (not global states)
# ============================================================================


@ft.observable
@dataclass
class UserObs:
    """Observable model for individual user with editing logic"""

    user: User
    is_editing: bool = False
    temp_first_name: str = ""
    temp_last_name: str = ""

    @property
    def first_name(self) -> str:
        return self.user.first_name

    @property
    def last_name(self) -> str:
        return self.user.last_name

    def start_edit(self):
        """Initialize editing mode"""
        self.temp_first_name = self.user.first_name
        self.temp_last_name = self.user.last_name
        self.is_editing = True

    def save(self):
        """Save changes to the domain model"""
        self.user.first_name = self.temp_first_name
        self.user.last_name = self.temp_last_name
        self.is_editing = False

    def cancel(self):
        """Cancel editing without saving"""
        self.is_editing = False


# ============================================================================
# GLOBAL STATES (auto-registered via State inheritance)
# ============================================================================


@ft.observable
@dataclass
class CounterState(State):
    """State for a simple counter example"""

    count: int = 0

    def increment(self):
        """Increment the counter"""
        self.count += 1

    def decrement(self):
        """Decrement the counter"""
        self.count -= 1


@ft.observable
@dataclass
class AppState(State):
    """Application-level state managing the collection"""

    users: list[UserObs] = field(default_factory=list)
    new_first_name: str = ""
    new_last_name: str = ""

    def add_user(self):
        """Add a new user to the collection"""
        if self.new_first_name.strip() or self.new_last_name.strip():
            user = User(first_name=self.new_first_name, last_name=self.new_last_name)
            user_obs = UserObs(user=user)
            self.users.append(user_obs)

            # 🎯 Access other states directly without subscription
            counter = CounterState.get_state()
            counter.increment()

            # Clear form
            self.new_first_name = ""
            self.new_last_name = ""

    def delete_user(self, user_obs: UserObs):
        """Remove a user from the collection"""
        counter = CounterState.get_state()  # 🎯 Direct access!
        self.users.remove(user_obs)
        counter.decrement()


# ============================================================================
# COMPONENTS
# ============================================================================


@ft.component
def UserView(user_obs: UserObs) -> ft.Control:
    """Displays a single user - read-only or editing mode"""
    app_state = AppState.use_state()  # 🎯 Direct access!

    if not user_obs.is_editing:
        return ft.Row(
            [
                ft.Text(f"{user_obs.first_name} {user_obs.last_name}"),
                ft.Button("Edit", on_click=lambda _: user_obs.start_edit()),
                ft.Button("Delete", on_click=lambda _: app_state.delete_user(user_obs)),
            ]
        )

    return ft.Row(
        [
            ft.TextField(
                label="First Name",
                value=user_obs.temp_first_name,
                on_change=lambda e: setattr(
                    user_obs, "temp_first_name", e.control.value
                ),
                width=180,
            ),
            ft.TextField(
                label="Last Name",
                value=user_obs.temp_last_name,
                on_change=lambda e: setattr(
                    user_obs, "temp_last_name", e.control.value
                ),
                width=180,
            ),
            ft.Button("Save", on_click=lambda _: user_obs.save()),
            ft.Button("Cancel", on_click=lambda _: user_obs.cancel()),
        ]
    )


@ft.component
def AddUserForm() -> ft.Control:
    """Form to add new users"""
    app_state = AppState.use_state()  # 🎯 Direct access!

    return ft.Row(
        [
            ft.TextField(
                label="First Name",
                width=200,
                value=app_state.new_first_name,
                on_change=lambda e: setattr(
                    app_state, "new_first_name", e.control.value
                ),
            ),
            ft.TextField(
                label="Last Name",
                width=200,
                value=app_state.new_last_name,
                on_change=lambda e: setattr(
                    app_state, "new_last_name", e.control.value
                ),
            ),
            ft.Button("Add", on_click=app_state.add_user),
        ]
    )


@ft.component
def UserNameRow() -> ft.Control:
    """Display all user names in a row"""
    users = AppState.use_state().users  # 🎯 Direct access!

    @ft.component
    def UserName(user_obs: UserObs) -> ft.Control:
        return ft.Text(f"{user_obs.first_name} {user_obs.last_name}")

    return ft.Row(
        [UserName(user_obs) for user_obs in users],
        spacing=50,
    )


@ft.component
def AppView(page: ft.Page) -> list[ft.Control]:
    """Root component - auto-initializes all registered states"""

    # 🎯 Initialize ALL registered states with one call
    State.init_all()

    # 🎯 Access them directly using ClassName.use_state()
    app_state = AppState.use_state()
    counter_state = CounterState.use_state()

    return [
        ft.Text(f"Session ID: {page.session.id}", size=12, color=ft.Colors.GREY),
        ft.Divider(),
        AddUserForm(),
        UserNameRow(),
        ft.Text(f"Total users: {counter_state.count}"),
        *[UserView(user_obs) for user_obs in app_state.users],
    ]


# ============================================================================
# RUN APP
# ============================================================================

ft.run(lambda page: page.render(lambda: AppView(page)))