Flet ASP - Flet Atomic State Pattern

📖 Overview

Flet ASP (Flet Atomic State Pattern) is a reactive state management library for Flet, bringing atom-based architecture and separation of concerns into Python apps — inspired by Flutter's Riverpod and ASP.

It provides predictable, testable, and declarative state through:

Atom – single reactive unit of state
Selector – derived/computed state
Action – handles async workflows like login, fetch, etc.

📦 Installation

Install using your package manager of choice:

# Pip
pip install flet-asp

# Poetry
poetry add flet-asp

# UV
uv add flet-asp

✨ Key Features

✅ Reactive atoms - Automatic UI updates when state changes
✅ Selectors - Derived/computed state (sync & async)
✅ Actions - Async-safe workflows for API calls, auth, etc.
✅ One-way & two-way binding - Seamless form input synchronization
✅ Hybrid update strategy - Bindings work even before controls are mounted
✅ Python 3.14+ optimizations - Free-threading, incremental GC, 3-5% faster
✅ Lightweight - No dependencies beyond Flet
✅ Type-safe - Full type hints support

🚀 Quick Start

1. Basic Counter (Your First Atom)

The simplest way to use Flet-ASP: create an atom, bind it to a control, and update it.

import flet as ft
import flet_asp as fa

def main(page: ft.Page):
    # Initialize state manager
    fa.get_state_manager(page)

    # Create a reactive atom
    page.state.atom("count", 0)

    # Create UI references
    count_text = ft.Ref[ft.Text]()

    def increment(e):
        # Update the atom - UI updates automatically!
        current = page.state.get("count")
        page.state.set("count", current + 1)

    # Build UI
    page.add(
        ft.Column([
            ft.Text("Counter", size=30),
            ft.Text(ref=count_text, size=50),
            ft.ElevatedButton("Increment", on_click=increment)
        ])
    )

    # Bind atom to UI - the Text will update automatically
    page.state.bind("count", count_text)

ft.app(target=main)

What's happening here?

atom("count", 0) - Creates a reactive piece of state
bind("count", count_text) - Connects state to UI
set("count", value) - Updates state → UI updates automatically!

2. Form with Two-Way Binding

Perfect for input fields that need to sync with state.

import flet as ft
import flet_asp as fa

def main(page: ft.Page):
    fa.get_state_manager(page)

    # Create atoms for form fields
    page.state.atom("email", "")
    page.state.atom("password", "")
    page.state.atom("message", "")  # Atom for login message

    # UI references
    email_field = ft.Ref[ft.TextField]()
    password_field = ft.Ref[ft.TextField]()
    message_text = ft.Ref[ft.Text]()

    def login(e):
        email = page.state.get("email")
        password = page.state.get("password")

        if email == "user@example.com" and password == "123":
            page.state.set("message", f"Welcome, {email}!")
        else:
            page.state.set("message", "Invalid credentials")
        # No page.update() needed - bind() handles it!

    page.add(
        ft.Column([
            ft.Text("Login Form", size=24),
            ft.TextField(ref=email_field, label="Email"),
            ft.TextField(ref=password_field, label="Password", password=True),
            ft.ElevatedButton("Login", on_click=login),
            ft.Text(ref=message_text)
        ])
    )

    # Two-way binding: TextField ↔ Atom
    page.state.bind_two_way("email", email_field)
    page.state.bind_two_way("password", password_field)
    page.state.bind("message", message_text)  # One-way binding for message

ft.app(target=main)

Key concept: bind_two_way() keeps the TextField and atom in perfect sync!

3. Computed State with Selectors

Derive new values from existing state automatically.

import flet as ft
import flet_asp as fa

def main(page: ft.Page):
    fa.get_state_manager(page)

    # Base atoms
    page.state.atom("first_name", "John")
    page.state.atom("last_name", "Doe")

    # Computed state - automatically recalculates when dependencies change
    @page.state.selector("full_name")
    def compute_full_name(get):
        return f"{get('first_name')} {get('last_name')}"

    # UI
    first_field = ft.Ref[ft.TextField]()
    last_field = ft.Ref[ft.TextField]()
    full_name_text = ft.Ref[ft.Text]()

    page.add(
        ft.Column([
            ft.Text("Name Builder", size=24),
            ft.TextField(ref=first_field, label="First Name"),
            ft.TextField(ref=last_field, label="Last Name"),
            ft.Divider(),
            ft.Text("Full Name:", weight=ft.FontWeight.BOLD),
            ft.Text(ref=full_name_text, size=20, color=ft.Colors.BLUE)
        ])
    )

    # Bind inputs
    page.state.bind_two_way("first_name", first_field)
    page.state.bind_two_way("last_name", last_field)

    # Bind computed state
    page.state.bind("full_name", full_name_text)

ft.app(target=main)

Magic! The full name updates automatically when first or last name changes.

4. Async Operations with Actions

Handle API calls, async operations, and side effects cleanly.

import asyncio
import flet as ft
import flet_asp as fa

def main(page: ft.Page):
    fa.get_state_manager(page)

    page.state.atom("user", None)
    page.state.atom("loading", False)
    page.state.atom("status", "")  # Atom for status message

    # Define async action
    async def login_action(get, set_value, params):
        set_value("loading", True)

        # Simulate API call
        await asyncio.sleep(2)

        # Validate credentials
        email = params.get("email")
        password = params.get("password")

        if email == "test@test.com" and password == "123":
            set_value("user", {"email": email, "name": "Test User"})
        else:
            set_value("user", None)

        set_value("loading", False)

    # Create action
    login = fa.Action(login_action)

    # UI
    email_field = ft.Ref[ft.TextField]()
    password_field = ft.Ref[ft.TextField]()
    status_text = ft.Ref[ft.Text]()

    async def handle_login(e):
        await login.run_async(
            page.state,
            {
                "email": email_field.current.value,
                "password": password_field.current.value
            }
        )

        user = page.state.get("user")
        if user:
            page.state.set("status", f"Welcome, {user['name']}!")
        else:
            page.state.set("status", "Login failed")
        # No page.update() needed - bind() handles it!

    # Selector to derive status from loading state
    @page.state.selector("loading_status")
    def compute_loading_status(get):
        return "Logging in..." if get("loading") else get("status")

    page.add(
        ft.Column([
            ft.Text("Async Login", size=24),
            ft.TextField(ref=email_field, label="Email"),
            ft.TextField(ref=password_field, label="Password", password=True),
            ft.ElevatedButton("Login", on_click=handle_login),
            ft.Text(ref=status_text)
        ])
    )

    # Bind selector to status text - fully declarative!
    page.state.bind("loading_status", status_text)

ft.app(target=main)

Actions encapsulate complex async logic in a testable, reusable way.

🤔 Listen, Selector, and Action: When to use each one?

Flet-ASP provides three powerful tools for managing reactive state. Understanding when to use each one is key to writing clean, performant code.

📊 Quick Comparison

Feature	`listen()`	`selector()`	`action()`
Purpose	Execute side effects	Calculate derived state	Execute business logic
Returns value?	❌ No	✅ Yes (creates atom)	❌ No
Execution	🔄 Automatic (reactive)	🔄 Automatic (reactive)	👆 Manual (on-demand)
Tracks dependencies	❌ No (1 atom only)	✅ Yes (automatic)	❌ No
Memoization	❌ No	✅ Yes (5-20x faster)	❌ No
Can modify state	✅ Yes (via `state.set()`)	❌ No (read-only)	✅ Yes (via `set()`)

📖 `listen()` - For Side Effects

Use listen() when you need to react to state changes with side effects (operations that don't produce state).

Common use cases:

Logging/debugging state changes
Sending analytics events
Syncing with localStorage or databases
Showing notifications
Making API calls when state changes

Example:

# Listen to user login to track analytics
page.state.listen("user", lambda user: send_analytics({
    "event": "user_login",
    "user_id": user["id"] if user else None
}))

# Debug state changes
page.state.listen("count", lambda value: print(f"Count changed: {value}"))

Key characteristics:

Listens to ONE atom at a time
Does NOT create new state
Executes immediately when the atom changes

🔄 `selector()` - For Derived State

Use selector() when you need to compute a value based on other atoms.

Common use cases:

Form validation (checking multiple fields)
Calculations (totals, averages, conversions)
Filtering/mapping lists
Formatting data (combining first + last name)
Combining multiple atoms into one value

Example:

# Validate form - automatically recalculates when email OR password changes
@page.state.selector("form_valid")
def validate_form(get):
    email = get("email")
    password = get("password")
    return bool(email and password and "@" in email and len(password) >= 6)

# Calculate cart total - recomputes when items change
@page.state.selector("cart_total")
def calculate_total(get):
    items = get("cart_items")
    return sum(item["price"] * item["quantity"] for item in items)

Key characteristics:

Tracks ALL dependencies automatically
Creates a new atom with the computed value
Memoized - only recalculates when dependencies change
5-20x faster than manual listeners for derivations

Why it's better than listen():

# ❌ With listen() - verbose, manual, no cache
def update_total(value):
    items = state.get("cart_items")
    tax = state.get("tax_rate")
    total = sum(i["price"] for i in items) * (1 + tax)
    state.set("total", total)

page.state.listen("cart_items", update_total)
page.state.listen("tax_rate", update_total)  # Duplicate code!

# ✅ With selector() - clean, automatic, cached
@page.state.selector("total")
def calculate_total(get):
    items = get("cart_items")
    tax = get("tax_rate")
    return sum(i["price"] for i in items) * (1 + tax)

⚡ `action()` - For Business Logic

Use action() when you need to execute complex operations that read and/or modify multiple atoms.

Common use cases:

Login/authentication workflows
Saving forms (validation + API call + state updates)
Checkout process (multiple state changes)
Resetting application state
Complex multi-step operations

Two ways to use:

Decorator style (recommended):

@page.state.action
def submit_form(get, set):
    # Read state
    email = get("email")
    password = get("password")

    # Validation
    if not email or not password:
        set("error", "Fill all fields")
        return

    # Update multiple atoms
    set("loading", True)
    set("error", None)

    # Business logic
    result = authenticate(email, password)

    if result.success:
        set("user", result.user)
        set("logged_in", True)
    else:
        set("error", result.message)

    set("loading", False)

# Call it manually
on_click=lambda _: submit_form()

Direct instantiation (advanced):

def submit_form_fn(get, set, args):
    email = get("email")
    # ... same logic ...

submit_form = fa.Action(submit_form_fn)

# Call with state
on_click=lambda _: submit_form.run(page.state)

# Or async
await submit_form.run_async(page.state, args={"extra": "data"})

Key characteristics:

Called manually (not reactive)
Can read and modify multiple atoms
Supports sync and async operations
Perfect for organizing complex workflows

🎯 Decision Tree: Which One To Use?

💡 Combining All Three

Here's a real-world example using all three together:

import flet as ft
import flet_asp as fa


class AuthResult:
    def __init__(self, success, user=None, message=None):
        self.success = success
        self.user = user
        self.message = message


def authenticate(email, password):
    import time
    time.sleep(2)  # Simulates API delay
    return AuthResult(
        success=True,
        user={
            "id": 1,
            "name": email
        }
    )


def send_analytics(param):
    print(param)


def main(page: ft.Page):
    state = fa.get_state_manager(page)

    # Atoms - raw data
    state.atom("email", "")
    state.atom("password", "")
    state.atom("user", None)
    state.atom("loading", False)

    # Selector - derived state (form validation)
    @state.selector("form_valid")
    def validate_form(get):
        """Automatically recalculates when email or password changes"""
        email = get("email")
        password = get("password")

        if not email or not password:
            return False

        if "@" in get("email"):
            return True

        return False

    # Listen - side effect (analytics)
    state.listen("user", lambda user: send_analytics({
        "event": "login",
        "user_id": user["id"] if user else None
    }))

    # Listen - reset user when fields are cleared
    def reset_user_on_clear(value):
        # If email or password is cleared, reset user
        email = state.get("email")
        password = state.get("password")
        if (not email or not password) and state.get("user"):
            state.set("user", None)

    state.listen("email", reset_user_on_clear)
    state.listen("password", reset_user_on_clear)

    # Action - business logic (login workflow)
    @state.action
    def login(get, set):
        """Executes when user clicks login button"""
        set("loading", True)

        email = get("email")
        password = get("password")

        # Call API
        result = authenticate(email, password)

        if result.success:
            set("user", result.user)  # ← This triggers the listen() above!
        else:
            set("error", result.message)

        set("loading", False)

    # UI
    email_ref = ft.Ref[ft.TextField]()
    password_ref = ft.Ref[ft.TextField]()
    login_btn = ft.Ref[ft.ElevatedButton]()
    loading_spinner = ft.Ref[ft.ProgressRing]()
    status_text = ft.Ref[ft.Text]()

    page.add(
        ft.Column([
            ft.Text("Login Form", size=24, weight=ft.FontWeight.BOLD),
            ft.Divider(),
            ft.TextField(ref=email_ref, label="Email"),
            ft.TextField(ref=password_ref, label="Password", password=True),
            ft.ElevatedButton(
                ref=login_btn,
                text="Login",
                on_click=lambda _: login(),  # ← Calls action manually
                visible=False  # ← Controlled by selector
            ),
            ft.Row([
                ft.ProgressRing(ref=loading_spinner, visible=False, width=20, height=20),
                ft.Text(ref=status_text, color=ft.Colors.GREEN, size=16)
            ])
        ])
    )

    # Selector to create the status message (derived from the user)
    @state.selector("status_message")
    def get_status_message(get):
        user = get("user")
        if user:
            return f"Welcome, {user['name']}!"
        return ""

    # Bindings
    state.bind_two_way("email", email_ref)
    state.bind_two_way("password", password_ref)
    state.bind("form_valid", login_btn, prop="visible")  # ← Selector binding
    state.bind("loading", loading_spinner, prop="visible")  # ← Loading spinner
    state.bind("status_message", status_text, prop="value")  # ← Status message (selector)


ft.app(target=main)

What's happening:

Selector validates the form and creates the status message automatically
Binding shows/hides button based on validation
Action handles login when button is clicked
Listen sends analytics when user state changes

📚 Best Practices

✅ DO:

Use selector() for any derived/computed state
Use listen() for side effects (logs, analytics, storage sync)
Use action() for complex workflows with multiple state changes
Combine all three when appropriate

❌ DON'T:

Don't use listen() to create derived state (use selector() instead)
Don't use action() for simple one-line state updates
Don't duplicate listeners when a selector can track dependencies automatically
Don't forget that selectors are memoized (much faster!)

📚 Advanced Usage

Custom Controls with Reactive State

Create reusable components with encapsulated state.

import flet as ft
import flet_asp as fa

class Counter(ft.Column):
    """Reusable counter component with its own state."""

    def __init__(self, page: ft.Page, counter_id: str, title: str):
        super().__init__()
        self.page = page
        self.counter_id = counter_id
        self.value_text = ft.Ref[ft.Text]()

        # Initialize state for this counter
        page.state.atom(f"{counter_id}_count", 0)

        self.controls = [
            ft.Container(
                content=ft.Column([
                    ft.Text(title, size=20, weight=ft.FontWeight.BOLD),
                    ft.Text(ref=self.value_text, size=40, color=ft.Colors.BLUE),
                    ft.Row([
                        ft.IconButton(
                            icon=ft.Icons.REMOVE,
                            on_click=self.decrement
                        ),
                        ft.IconButton(
                            icon=ft.Icons.ADD,
                            on_click=self.increment
                        )
                    ], alignment=ft.MainAxisAlignment.CENTER)
                ], horizontal_alignment=ft.CrossAxisAlignment.CENTER),
                padding=20,
                border=ft.border.all(2, ft.Colors.BLUE),
                border_radius=10
            )
        ]

    def did_mount(self):
        # Bind when component is mounted
        self.page.state.bind(f"{self.counter_id}_count", self.value_text)

    def increment(self, e):
        current = self.page.state.get(f"{self.counter_id}_count")
        self.page.state.set(f"{self.counter_id}_count", current + 1)

    def decrement(self, e):
        current = self.page.state.get(f"{self.counter_id}_count")
        self.page.state.set(f"{self.counter_id}_count", current - 1)

def main(page: ft.Page):
    fa.get_state_manager(page)

    page.add(
        ft.Column([
            ft.Text("Multiple Counters", size=30),
            ft.Row([
                Counter(page, "counter1", "Counter A"),
                Counter(page, "counter2", "Counter B"),
                Counter(page, "counter3", "Counter C")
            ])
        ])
    )

ft.app(target=main)

Navigation with State Preservation

State persists across navigation automatically!

import flet as ft
import flet_asp as fa

def home_screen(page: ft.Page):
    """Home screen with shared state."""
    count_text = ft.Ref[ft.Text]()

    def go_to_settings(e):
        page.views.clear()
        page.views.append(settings_screen(page))
        page.update()

    return ft.View(
        "/",
        [
            ft.AppBar(title=ft.Text("Home"), bgcolor=ft.Colors.BLUE),
            ft.Column([
                ft.Text("Counter Value:", size=20),
                ft.Text(ref=count_text, size=50, color=ft.Colors.BLUE),
                ft.ElevatedButton("Go to Settings", on_click=go_to_settings)
            ])
        ]
    )

def settings_screen(page: ft.Page):
    """Settings screen - modifies shared state."""

    def increment(e):
        current = page.state.get("count")
        page.state.set("count", current + 1)

    def go_back(e):
        page.views.clear()
        page.views.append(home_screen(page))
        page.update()

    return ft.View(
        "/settings",
        [
            ft.AppBar(title=ft.Text("Settings"), bgcolor=ft.Colors.GREEN),
            ft.Column([
                ft.Text("Modify Counter", size=20),
                ft.ElevatedButton("Increment", on_click=increment),
                ft.ElevatedButton("Go Back", on_click=go_back)
            ])
        ]
    )

def main(page: ft.Page):
    fa.get_state_manager(page)

    # Shared state across screens
    page.state.atom("count", 0)

    page.views.append(home_screen(page))

    # Bind state after adding view (works with hybrid strategy!)
    count_ref = page.views[0].controls[1].controls[1]  # Get the count text
    page.state.bind("count", ft.Ref[ft.Text]())

ft.app(target=main)

Global State Outside Page Scope

For advanced scenarios like testing, multi-window applications, or complex state architectures, you can create a StateManager outside the page scope.

import flet as ft
import flet_asp as fa

# Create global StateManager OUTSIDE the page
global_state = fa.StateManager()

def screen_a(page: ft.Page):
    """Main screen with counter."""
    count_ref = ft.Ref[ft.Text]()

    def increment(e):
        # Use global_state instead of page.state
        global_state.set("count", global_state.get("count") + 1)

    def go_to_b(e):
        page.go("/b")

    view = ft.View(
        "/",
        [
            ft.Text("Screen A - Global State", size=24, weight=ft.FontWeight.BOLD),
            ft.Text(ref=count_ref, size=40, color=ft.Colors.BLUE_700),
            ft.ElevatedButton("Increment", on_click=increment),
            ft.ElevatedButton("Go to Screen B", on_click=go_to_b),
        ],
        padding=20,
    )

    # Bind using global_state
    global_state.bind("count", count_ref)
    return view

def screen_b(page: ft.Page):
    """Secondary screen displaying the counter."""
    def go_back(e):
        page.go("/")

    return ft.View(
        "/b",
        [
            ft.Text("Screen B - Global State", size=24, weight=ft.FontWeight.BOLD),
            ft.Text(f"Counter value: {global_state.get('count')}", size=16),
            ft.Text("State is managed globally!", color=ft.Colors.GREEN_700),
            ft.ElevatedButton("Go back", on_click=go_back),
        ],
        padding=20,
    )

def main(page: ft.Page):
    """App entry point."""
    # IMPORTANT: Attach the page to the global StateManager
    global_state.page = page

    # Initialize atoms
    global_state.atom("count", 0)

    def route_change(e):
        page.views.clear()
        if page.route == "/b":
            page.views.append(screen_b(page))
        else:
            page.views.append(screen_a(page))
        page.update()

    page.on_route_change = route_change
    page.go("/")

ft.app(target=main)

When to use global state:

Use Case	Why Global State?
Unit Testing	Test state logic without creating a Flet page
Multi-Window Apps	Share state between multiple page instances
Advanced Architectures	State exists independently of UI lifecycle
Framework Integration	Flet-ASP as part of a larger system

Key differences:

Aspect	`page.state`	`global_state`
Creation	`fa.get_state_manager(page)`	`fa.StateManager()`
Page binding	Automatic	Manual (`global_state.page = page`)
Scope	Inside `main()`	Global (module level)
Lifecycle	Managed by page	Manual
When to use	✅ Most cases	⚠️ Specific scenarios

Common pitfalls:

# ❌ WRONG - Forgot to attach page
global_state = fa.StateManager()

def main(page: ft.Page):
    global_state.atom("count", 0)  # Error: page not attached!

# ✅ CORRECT - Attach page first
global_state = fa.StateManager()

def main(page: ft.Page):
    global_state.page = page  # Attach first!
    global_state.atom("count", 0)

Testing example:

import unittest
import flet_asp as fa

# Global state for testing
test_state = fa.StateManager()

class TestMyLogic(unittest.TestCase):
    def setUp(self):
        test_state._atoms.clear()
        test_state.atom("count", 0)

    def test_increment(self):
        # Test logic without creating a Flet page
        test_state.set("count", test_state.get("count") + 1)
        self.assertEqual(test_state.get("count"), 1)

    def test_computed_value(self):
        test_state.atom("double", lambda: test_state.get("count") * 2)
        test_state.set("count", 5)
        self.assertEqual(test_state.get("double"), 10)

For a complete example, see 11.1_global_state_outside.py.

Complex Selectors with Async Data

Fetch and compute data asynchronously.

import asyncio
import flet as ft
import flet_asp as fa

def main(page: ft.Page):
    fa.get_state_manager(page)

    # Base atoms
    page.state.atom("user_id", 1)

    # Async selector - fetches user data
    @page.state.selector("user_data")
    async def fetch_user(get):
        user_id = get("user_id")

        # Simulate API call
        await asyncio.sleep(1)

        # Mock user data
        users = {
            1: {"name": "Alice", "email": "alice@example.com"},
            2: {"name": "Bob", "email": "bob@example.com"},
            3: {"name": "Charlie", "email": "charlie@example.com"}
        }

        return users.get(user_id, {"name": "Unknown", "email": "N/A"})

    # UI
    user_info = ft.Ref[ft.Text]()

    # Selector to format user info (depends on async selector)
    @page.state.selector("user_display")
    def format_user_display(get):
        user_data = get("user_data")
        # Async selectors return None while loading
        if user_data is None:
            return "Loading..."
        return f"{user_data['name']} ({user_data['email']})"

    def next_user(e):
        current_id = page.state.get("user_id")
        page.state.set("user_id", (current_id % 3) + 1)

    page.add(
        ft.Column([
            ft.Text("User Profile", size=24),
            ft.Text(ref=user_info, size=18),
            ft.ElevatedButton("Next User", on_click=next_user)
        ])
    )

    # Bind selector to text - no page.update() needed!
    page.state.bind("user_display", user_info)

ft.app(target=main)

Shopping Cart Example

Real-world e-commerce state management.

import flet as ft
import flet_asp as fa

def main(page: ft.Page):
    fa.get_state_manager(page)

    # State
    page.state.atom("cart_items", [])

    # Selectors
    @page.state.selector("cart_total")
    def calculate_total(get):
        items = get("cart_items")
        total = sum(item["price"] * item["quantity"] for item in items)
        return f"Total: ${total:.2f}"

    @page.state.selector("cart_count")
    def count_items(get):
        items = get("cart_items")
        count = sum(item["quantity"] for item in items)
        return f"Items: {count}"

    # Available products
    products = [
        {"id": 1, "name": "Laptop", "price": 999.99},
        {"id": 2, "name": "Mouse", "price": 29.99},
        {"id": 3, "name": "Keyboard", "price": 79.99}
    ]

    # UI refs
    cart_list = ft.Ref[ft.Column]()
    cart_count_text = ft.Ref[ft.Text]()
    cart_total_text = ft.Ref[ft.Text]()

    def add_to_cart(product):
        items = page.state.get("cart_items")

        # Check if item already in cart
        existing = next((item for item in items if item["id"] == product["id"]), None)

        if existing:
            # Create new list with updated item (immutable update)
            new_items = [
                {**item, "quantity": item["quantity"] + 1} if item["id"] == product["id"] else item
                for item in items
            ]
        else:
            # Create new list with new item
            new_items = [*items, {**product, "quantity": 1}]

        page.state.set("cart_items", new_items)

    def render_cart():
        """
        Note: This uses page.update() because we're dynamically creating
        control lists. For simple value bindings, use state.bind() instead.
        """
        items = page.state.get("cart_items")

        cart_list.current.controls = [
            ft.ListTile(
                title=ft.Text(item["name"]),
                subtitle=ft.Text(f"${item['price']:.2f} × {item['quantity']}"),
                trailing=ft.Text(f"${item['price'] * item['quantity']:.2f}")
            ) for item in items
        ] if items else [ft.Text("Cart is empty")]

        cart_list.current.update()  # Update only the cart list, not the whole page

    # Listen to cart changes (immediate=False to avoid calling before UI is mounted)
    page.state.listen("cart_items", lambda _: render_cart(), immediate=False)

    # Build UI
    page.add(
        ft.Row([
            # Products column
            ft.Column([
                ft.Text("Products", size=24),
                *[
                    ft.ElevatedButton(
                        f"{p['name']} - ${p['price']:.2f}",
                        on_click=lambda e, product=p: add_to_cart(product)
                    ) for p in products
                ]
            ], expand=1),

            # Cart column
            ft.Column([
                ft.Text("Shopping Cart", size=24),
                ft.Text(ref=cart_count_text),
                ft.Column(ref=cart_list),
                ft.Divider(),
                ft.Text(ref=cart_total_text, size=20, weight=ft.FontWeight.BOLD)
            ], expand=1)
        ])
    )

    # Bind computed values
    page.state.bind("cart_count", cart_count_text, prop="value")
    page.state.bind("cart_total", cart_total_text, prop="value")

    render_cart()

ft.app(target=main)

⚡ Performance & Python 3.14+

Flet-ASP includes a hybrid update strategy that ensures bindings work reliably, even when controls are bound before being added to the page.

Hybrid Strategy:

Lazy updates - Property is always set (never fails)
Immediate updates - Tries to update if control is mounted (99% of cases)
Lifecycle hooks - Hooks into did_mount for custom controls
Queue fallback - Retries when page.update() is called

Python 3.14+ Optimizations:

Feature	Benefit	Performance Gain
Free-threading	Process bindings in parallel without GIL	Up to 4x faster for large apps
Incremental GC	Smaller garbage collection pauses	10x smaller pauses (20ms → 2ms)
Tail call interpreter	Faster Python execution	3-5% overall speedup

Configuration (optional):

from flet_asp.atom import Atom

# For giant apps with 1000+ bindings on Python 3.14+
Atom.MAX_PARALLEL_BINDS = 8

# For small apps or to disable free-threading
Atom.ENABLE_FREE_THREADING = False

For more details, see PERFORMANCE.md.

📁 More Examples

Explore the examples/ folder for complete applications:

Basic Examples:

1.0_counter_atom.py - Simple counter
1.1_counter_atom_using_state_alias.py - Counter with page.state
2_counter_atom_bind_dynamic.py - Dynamic binding

Intermediate Examples:

3_computed_fullname.py - Computed state
4_action_login.py - Async actions
5_selector_user_email.py - Selectors
6_listen_user_login.py - State listeners
7_bind_two_way_textfield.py - Two-way binding
8_session_reset_clear.py - State cleanup

Advanced Examples:

9_todo.py - Complete ToDo app
10_cart_app.py - Shopping cart
11_screen_a_navigation_screen_b.py - Navigation with page.state
11.1_global_state_outside.py - Global state outside page scope
12_python314_performance.py - Performance demo
13_hybrid_binding_advanced.py - Hybrid binding

Atomic Design Examples:

14_atomic_design_dashboard/ - Complete dashboard with atoms, molecules, organisms, templates, and pages
15_atomic_design_theming/ - Theme-aware component library with design tokens
16_reactive_atomic_components/ - Reactive components with built-in state management
17_atomic_design_send_button/ - Send button with reactive state management

🧩 Building Design Systems with Atomic Design

Flet-ASP is designed from the ground up to work seamlessly with the Atomic Design methodology - a powerful approach for building scalable, maintainable design systems.

What is Atomic Design?

Atomic Design is a methodology for creating design systems by breaking down interfaces into fundamental building blocks, inspired by chemistry:

🔬 Atoms → 🧪 Molecules → 🧬 Organisms → 📄 Templates → 📱 Pages

How Flet-ASP Maps to Atomic Design

Atomic Design Layer	Flet-ASP Feature	Example
Atoms	Reactive state values	`page.state.atom("email", "")`
Molecules	Computed state	`@page.state.selector("full_name")`
Organisms	Actions & workflows	`Action(login_function)`
Templates	State bindings	`page.state.bind("count", ref)`
Pages	Complete screens	Custom controls with encapsulated state

Real-World Atomic Design with Flet-ASP

We provide two comprehensive examples that demonstrate professional design system architecture:

📊 Example 14: Dashboard Design System

A complete dashboard application showcasing the full Atomic Design hierarchy:

Atoms: Buttons, inputs, text styles, icons, dividers
Molecules: Stat cards, menu items, form fields, search bars
Organisms: Sidebar, top bar, data tables, stats grid
Templates: Dashboard layouts with different content arrangements
Pages: Dashboard, analytics, users, orders, settings screens

# Atoms define the foundation
from atoms import heading1, primary_button

# Molecules combine atoms
from molecules import stat_card

# Organisms compose molecules
from organisms import stats_grid

# Templates arrange organisms
from templates import dashboard_template

# Pages bring it all together
from pages import dashboard_page

Features:

✅ Complete component hierarchy following Atomic Design
✅ Real-time data updates with reactive state bindings
✅ Navigation with state preservation
✅ Reusable components across multiple pages
✅ Consistent design language

View Example →

🎨 Example 15: Theme-Aware Component Library

An advanced example demonstrating design tokens and dynamic theming:

Design Tokens: Colors, typography, spacing, border radius
Theme-Aware Atoms: Components that adapt to light/dark modes
Reactive Theming: Real-time theme switching with flet-asp
Semantic Colors: Success, warning, error, info states

from theme_tokens import get_theme
from atoms import filled_button, text_field
from molecules import alert, stat_card

# All components automatically adapt to current theme
theme = get_theme()
button = filled_button("Submit")  # Uses theme.colors.primary

Features:

✅ Complete design token system (colors, typography, spacing)
✅ Light and dark mode support
✅ Theme switching without page reload
✅ Semantic color system for alerts and states
✅ Professional design system architecture

View Example →

⚛️ Example 16: Reactive Atomic Components

Components that combine visual structure + reactive state in a single, reusable package:

from reactive_atoms import ReactiveCounter, ReactiveStatCard, ReactiveForm

# Create counter with built-in state!
counter = ReactiveCounter(page, "Counter A", initial_count=0)
page.add(counter.control)

# Interact via clean API
counter.increment()  # +1
counter.decrement()  # -1
counter.reset()      # Set to 0
print(counter.value) # Get current value

# Stat card with auto-updates
users_card = ReactiveStatCard(
    page,
    title="Total Users",
    atom_key="users",
    initial_value="1,234",
    icon_name=ft.Icons.PEOPLE,
    show_trend=True
)

# Update programmatically
users_card.update_with_trend("2,500", "+15%")  # ✨ UI updates automatically!

Features:

✅ Components with built-in reactive state
✅ No manual binding needed
✅ Clean, intuitive API
✅ Encapsulated state management
✅ Reusable across projects

View Example →

Why Atomic Design + Flet-ASP?

🎯 Consistency: Design tokens and atoms ensure uniform styling across your app

🔄 Reusability: Build components once, use them everywhere with different state bindings

📈 Scalability: Add new features by combining existing atoms and molecules

🧪 Testability: Test atoms, molecules, and organisms in isolation

🤝 Collaboration: Designers and developers work with the same component language

⚡ Reactivity: State changes propagate automatically through the component hierarchy

Learn More About Atomic Design

Atomic Design by Brad Frost - The definitive guide
Building Design Systems with Atomic Design
Material Design System - Real-world example
Flet-ASP Examples - Practical implementations

🌐 Community

Join the community to contribute or get help:

⭐ Support

If you like this project, please give it a GitHub star ⭐

🤝 Contributing

Contributions and feedback are welcome!

Fork the repository
Create a feature branch
Submit a pull request with detailed explanation

For feedback, open an issue with your suggestions.

Commit your work to the LORD, and your plans will succeed. Proverbs 16:3

Name		Name	Last commit message	Last commit date
Latest commit History 77 Commits
.github/workflows		.github/workflows
assets/images		assets/images
examples		examples
flet_asp		flet_asp
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
PERFORMANCE.md		PERFORMANCE.md
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Flet ASP - Flet Atomic State Pattern

📖 Overview

📦 Installation

✨ Key Features

🚀 Quick Start

1. Basic Counter (Your First Atom)

2. Form with Two-Way Binding

3. Computed State with Selectors

4. Async Operations with Actions

🤔 Listen, Selector, and Action: When to use each one?

📊 Quick Comparison

📖 listen() - For Side Effects

🔄 selector() - For Derived State

⚡ action() - For Business Logic

Decorator style (recommended):

Direct instantiation (advanced):

🎯 Decision Tree: Which One To Use?

💡 Combining All Three

📚 Best Practices

📚 Advanced Usage

Custom Controls with Reactive State

Navigation with State Preservation

Global State Outside Page Scope

Complex Selectors with Async Data

Shopping Cart Example

⚡ Performance & Python 3.14+

Hybrid Strategy:

Python 3.14+ Optimizations:

📁 More Examples

🧩 Building Design Systems with Atomic Design

What is Atomic Design?

How Flet-ASP Maps to Atomic Design

Real-World Atomic Design with Flet-ASP

📊 Example 14: Dashboard Design System

🎨 Example 15: Theme-Aware Component Library

⚛️ Example 16: Reactive Atomic Components

Why Atomic Design + Flet-ASP?

Learn More About Atomic Design

🌐 Community

⭐ Support

🤝 Contributing

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

📖 `listen()` - For Side Effects

🔄 `selector()` - For Derived State

⚡ `action()` - For Business Logic

Packages