Reflex Dev

Reflex Development

Overview

Reflex is a full-stack Python framework for building web applications without writing JavaScript. Apps compile to a React frontend and FastAPI backend, with state management and event handlers running entirely in Python.

Architecture:

• Frontend: Compiled to React (JavaScript) for UI rendering
• Backend: FastAPI server running Python event handlers
• Communication: WebSockets for real-time state updates
• State: Server-side Python state synchronized to frontend

Core Concepts

State Management

State is a Python class that holds all mutable data and event handlers. All state variables must be JSON-serializable.

import reflex as rx

class AppState(rx.State):
    # State variables (any JSON-serializable type)
    count: int = 0
    items: list[str] = []
    user_name: str = ""

    # Event handlers - the ONLY way to modify state
    def increment(self):
        self.count += 1

    def add_item(self, item: str):
        self.items.append(item)

    # Computed vars (derived state)
    @rx.var
    def item_count(self) -> int:
        return len(self.items)

Key Rules:

• State vars MUST be JSON-serializable (int, str, list, dict, bool, float)
• Only event handlers can modify state
• Use @rx.var decorator for computed/derived values
• State is per-user session (isolated between users)

Components

Components are UI building blocks. Reflex provides 60+ built-in components.

import reflex as rx

def header() -> rx.Component:
    return rx.heading("My App", size="lg")

def counter_component(state: AppState) -> rx.Component:
    return rx.vstack(
        rx.text(f"Count: {state.count}"),
        rx.button("Increment", on_click=state.increment),
        spacing="4"
    )

Common Components:

• Layout: rx.vstack, rx.hstack, rx.box, rx.container
• Text: rx.heading, rx.text, rx.code
• Input: rx.input, rx.text_area, rx.select, rx.checkbox
• Interactive: rx.button, rx.link, rx.icon_button
• Data: rx.table, rx.data_table, rx.list
• Charts: rx.recharts.line_chart, rx.recharts.bar_chart, etc.

Event Handlers

Event handlers respond to user interactions and are the ONLY way to modify state.

class FormState(rx.State):
    form_data: dict[str, str] = {}

    # Simple event handler
    def handle_submit(self):
        print(f"Submitted: {self.form_data}")

    # Event handler with argument
    def update_field(self, field: str, value: str):
        self.form_data[field] = value

    # Async event handler (for API calls, DB queries)
    async def fetch_data(self):
        # Can use any Python library
        import httpx
        async with httpx.AsyncClient() as client:
            response = await client.get("https://api.example.com/data")
            self.data = response.json()

Event Triggers (connect components to handlers):

• on_click: Button clicks
• on_change: Input field changes
• on_submit: Form submissions
• on_mount: Component first renders
• on_blur, on_focus: Input focus events

Project Structure

Standard Reflex app structure:

my_app/
├── my_app/
│   ├── __init__.py         # Empty
│   └── my_app.py           # Main app file (State + pages)
├── assets/                 # Static files (images, fonts, etc.)
├── .web/                   # Auto-generated frontend (don't edit)
├── rxconfig.py             # Reflex configuration
└── requirements.txt        # Python dependencies

Main App File Pattern

import reflex as rx

# 1. Define State
class State(rx.State):
    count: int = 0

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

# 2. Define Pages
def index() -> rx.Component:
    return rx.container(
        rx.heading("Welcome"),
        rx.button("Click", on_click=State.increment),
        rx.text(f"Count: {State.count}")
    )

def about() -> rx.Component:
    return rx.container(
        rx.heading("About"),
        rx.link("Home", href="/")
    )

# 3. Create App and Add Routes
app = rx.App()
app.add_page(index, route="/")
app.add_page(about, route="/about")

Common Patterns

Form Handling

class FormState(rx.State):
    name: str = ""
    email: str = ""

    def handle_submit(self, form_data: dict):
        self.name = form_data.get("name", "")
        self.email = form_data.get("email", "")

def form_page():
    return rx.form(
        rx.vstack(
            rx.input(name="name", placeholder="Name"),
            rx.input(name="email", placeholder="Email"),
            rx.button("Submit", type="submit"),
        ),
        on_submit=FormState.handle_submit,
    )

Data Tables

class DataState(rx.State):
    data: list[dict] = [
        {"id": 1, "name": "Alice", "age": 25},
        {"id": 2, "name": "Bob", "age": 30},
    ]

def data_table_page():
    return rx.data_table(
        data=DataState.data,
        columns=["id", "name", "age"],
        sort=True,
        search=True,
        pagination=True,
    )

File Upload

class UploadState(rx.State):
    async def handle_upload(self, files: list[rx.UploadFile]):
        for file in files:
            upload_data = await file.read()
            # Process file data
            outfile = f"./uploads/{file.filename}"
            with open(outfile, "wb") as f:
                f.write(upload_data)

def upload_page():
    return rx.vstack(
        rx.upload(
            rx.button("Select Files"),
            id="upload1",
        ),
        rx.button(
            "Upload",
            on_click=UploadState.handle_upload(rx.upload_files(upload_id="upload1"))
        ),
    )

Database Integration (with DuckDB)

import duckdb
import polars as pl

class DBState(rx.State):
    records: list[dict] = []

    async def load_data(self):
        # Use existing database connection
        conn = duckdb.connect("data/mydb.duckdb")
        df = conn.execute("SELECT * FROM mytable").pl()
        self.records = df.to_dicts()
        conn.close()

    async def insert_record(self, data: dict):
        conn = duckdb.connect("data/mydb.duckdb")
        conn.execute(
            "INSERT INTO mytable (name, value) VALUES (?, ?)",
            [data["name"], data["value"]]
        )
        conn.close()
        await self.load_data()  # Refresh

Styling & Layout

Inline Styling

rx.box(
    rx.text("Styled text"),
    bg="#1a5f9e",
    color="white",
    padding="4",
    border_radius="md",
)

Responsive Layout

rx.container(
    rx.responsive_grid(
        rx.box("Item 1", bg="blue"),
        rx.box("Item 2", bg="green"),
        rx.box("Item 3", bg="red"),
        columns=[1, 2, 3],  # 1 col mobile, 2 tablet, 3 desktop
        spacing="4",
    ),
    max_width="1200px",
)

Common Style Props

• Layout: width, height, padding, margin, display
• Colors: bg (background), color (text)
• Typography: font_size, font_weight, text_align
• Borders: border, border_radius, border_color
• Spacing: spacing (for stacks), gap

Routing

Multiple Pages

app = rx.App()

# Route with parameters
@rx.page(route="/user/[id]")
def user_page() -> rx.Component:
    return rx.text(f"User ID: {State.router.page.params.get('id')}")

# Simple routes
app.add_page(index, route="/")
app.add_page(about, route="/about")

Navigation

# Links
rx.link("Go to About", href="/about")

# Programmatic navigation
def go_home(self):
    return rx.redirect("/")

Development Workflow

Initialize New App

pip install reflex
reflex init

Run Development Server

reflex run

App runs on http://localhost:3000 with auto-reload.

Common Commands

reflex run          # Start dev server
reflex export       # Build production bundle
reflex db init      # Initialize database (if using Reflex DB)
reflex db migrate   # Run migrations

Best Practices

1. State Organization: Split large states into substates

   class AuthState(rx.State):
       user: str = ""

   class DataState(rx.State):
       items: list = []

2. Component Reusability: Create reusable component functions

   def card(title: str, content: str) -> rx.Component:
       return rx.box(
           rx.heading(title, size="md"),
           rx.text(content),
           padding="4",
           border="1px solid #ddd",
       )

3. Event Handler Performance: Use async for I/O operations

   async def fetch_data(self):
       # Async I/O won't block other users
       self.data = await some_api_call()

4. Type Hints: Always type-hint state vars and event handlers

   count: int = 0
   items: list[str] = []

   def update_count(self, value: int) -> None:
       self.count = value

References

Documentation

• Official Docs: https://reflex.dev/docs/getting-started/introduction/
• Component Library: https://reflex.dev/docs/library
• Tutorials: https://reflex.dev/docs/getting-started/tutorial/

Example Apps

See examples/ directory for complete working examples:

• Simple counter app
• Data table with CRUD operations
• Form with validation
• File upload and processing

Common Patterns Reference

See references/patterns.md for detailed examples of:

• Authentication flows
• Real-time updates
• Complex form validation
• Multi-step workflows
• Data visualization with charts

Reflex Examples

Complete, working Reflex applications demonstrating common patterns and features.

Running Examples

Each example is a standalone Reflex app. To run:

1. Install Reflex:

   pip install reflex

2. Navigate to this directory and copy the example:

   cp counter_app.py my_app.py

3. Initialize and run:

   reflex init
   reflex run

4. Open browser to http://localhost:3000

Available Examples

1. Counter App (counter_app.py)

Demonstrates:

• Basic state management
• Event handlers
• Component composition
• Inline styling

Features:

• Increment/decrement counter
• Configurable step size
• Reset functionality

Best For: Learning Reflex basics, understanding state and event handlers

---

2. Data Table with CRUD (data_table_crud.py)

Demonstrates:

• List state management
• CRUD operations (Create, Read, Update, Delete)
• Forms with conditional rendering
• Data tables
• Computed vars

Features:

• View user data in table
• Add new users
• Edit existing users
• Delete users
• Form validation

Best For: Building admin panels, data management interfaces

---

3. Form with Validation (form_validation.py)

Demonstrates:

• Complex form handling
• Real-time validation
• Error messages
• Conditional rendering
• Component reusability

Features:

• Username validation (length, characters)
• Email validation (format)
• Password validation (strength requirements)
• Password confirmation matching
• Terms agreement checkbox
• Success/error states

Best For: User registration, complex forms, input validation

---

4. File Upload (file_upload.py)

Demonstrates:

• File upload handling
• Async operations
• Progress feedback
• File type validation
• File management

Features:

• Multi-file upload
• File type restrictions
• Upload progress
• File list with metadata
• File deletion
• Size calculations

Best For: Document management, media uploads, data import

Customization Tips

Styling

All examples use inline styling. You can customize colors, spacing, and layout by modifying style props:

rx.box(
    bg="#your-color",
    padding="4",
    border_radius="md",
)

State Extension

Add more state variables and event handlers to extend functionality:

class MyState(rx.State):
    new_feature: str = ""

    def new_handler(self):
        # Your logic
        pass

Component Reuse

Extract common patterns into reusable functions:

def custom_button(text: str, handler) -> rx.Component:
    return rx.button(
        text,
        on_click=handler,
        color_scheme="blue",
        size="lg",
    )

Integration with Existing Projects

These examples can be integrated into the Monaco Payroll System:

1. Data Table CRUD - Adapt for employee management, payroll record editing 2. Form Validation - Use for employee data entry, validation rules 3. File Upload - Integrate with Excel import/export functionality 4. Counter App - Adapt for statistics, counters in dashboard

Additional Resources

• Reflex Documentation: https://reflex.dev/docs
• Component Library: https://reflex.dev/docs/library
• Community Examples: https://github.com/reflex-dev/reflex-examples
• Monaco Payroll Integration: See references/patterns.md for DuckDB/Polars patterns

Common Reflex Patterns

This reference provides detailed examples of common patterns in Reflex applications.

Authentication Flows

Basic Authentication with Session State

import reflex as rx
import bcrypt


class AuthState(rx.State):
    """Authentication state management."""

    username: str = ""
    is_authenticated: bool = False
    error_message: str = ""

    def login(self, form_data: dict):
        """Handle login with username/password."""
        username = form_data.get("username", "")
        password = form_data.get("password", "")

        # In production: check against database
        # For demo: simple hardcoded check
        if username == "admin" and password == "password":
            self.username = username
            self.is_authenticated = True
            return rx.redirect("/dashboard")
        else:
            self.error_message = "Invalid credentials"

    def logout(self):
        """Clear session and redirect to login."""
        self.username = ""
        self.is_authenticated = False
        return rx.redirect("/login")

    def check_auth(self):
        """Redirect to login if not authenticated."""
        if not self.is_authenticated:
            return rx.redirect("/login")


def login_page():
    return rx.container(
        rx.form(
            rx.vstack(
                rx.heading("Login"),
                rx.input(name="username", placeholder="Username"),
                rx.input(name="password", type="password", placeholder="Password"),
                rx.cond(
                    AuthState.error_message != "",
                    rx.text(AuthState.error_message, color="red"),
                    rx.box(),
                ),
                rx.button("Login", type="submit"),
            ),
            on_submit=AuthState.login,
        ),
    )


def protected_page():
    return rx.container(
        rx.vstack(
            rx.heading(f"Welcome, {AuthState.username}!"),
            rx.button("Logout", on_click=AuthState.logout),
        ),
        on_mount=AuthState.check_auth,
    )

Protected Routes Pattern

def require_auth(page_func):
    """Decorator to protect routes."""
    def wrapper():
        return rx.cond(
            AuthState.is_authenticated,
            page_func(),
            rx.redirect("/login"),
        )
    return wrapper


@require_auth
def admin_page():
    return rx.container(
        rx.heading("Admin Dashboard"),
        # Admin content
    )

Real-Time Updates

WebSocket State Updates

import reflex as rx
import asyncio


class LiveDataState(rx.State):
    """Real-time data updates."""

    current_value: float = 0.0
    data_points: list[float] = []
    is_streaming: bool = False

    async def start_streaming(self):
        """Start streaming data updates."""
        self.is_streaming = True

        while self.is_streaming:
            # Simulate real-time data (replace with actual data source)
            import random
            self.current_value = random.uniform(0, 100)
            self.data_points.append(self.current_value)

            # Keep only last 50 points
            if len(self.data_points) > 50:
                self.data_points = self.data_points[-50:]

            # Update every second
            await asyncio.sleep(1)

    def stop_streaming(self):
        """Stop streaming."""
        self.is_streaming = False


def live_dashboard():
    return rx.vstack(
        rx.heading(f"Current Value: {LiveDataState.current_value:.2f}"),
        rx.recharts.line_chart(
            rx.recharts.line(data_key="value"),
            data=[{"value": v} for v in LiveDataState.data_points],
            width="100%",
            height=300,
        ),
        rx.button(
            "Start Streaming",
            on_click=LiveDataState.start_streaming,
            disabled=LiveDataState.is_streaming,
        ),
        rx.button(
            "Stop Streaming",
            on_click=LiveDataState.stop_streaming,
            disabled=~LiveDataState.is_streaming,
        ),
    )

Auto-Refresh Pattern

class RefreshState(rx.State):
    """Auto-refresh data at intervals."""

    data: list[dict] = []
    last_updated: str = ""

    async def auto_refresh(self):
        """Refresh data every N seconds."""
        while True:
            await self.load_data()
            await asyncio.sleep(30)  # Refresh every 30 seconds

    async def load_data(self):
        """Load data from source."""
        # Replace with actual data loading
        from datetime import datetime
        self.data = await fetch_from_api()
        self.last_updated = datetime.now().strftime("%H:%M:%S")


def auto_refresh_page():
    return rx.container(
        rx.vstack(
            rx.text(f"Last updated: {RefreshState.last_updated}"),
            # Display data
        ),
        on_mount=RefreshState.auto_refresh,
    )

Complex Form Validation

Multi-Step Form

class MultiStepFormState(rx.State):
    """Multi-step form with validation."""

    # Current step
    current_step: int = 1

    # Step 1: Personal info
    first_name: str = ""
    last_name: str = ""
    email: str = ""

    # Step 2: Address
    street: str = ""
    city: str = ""
    zip_code: str = ""

    # Step 3: Preferences
    newsletter: bool = False
    notifications: bool = True

    @rx.var
    def step1_valid(self) -> bool:
        """Check if step 1 is complete."""
        return (
            len(self.first_name) > 0 and
            len(self.last_name) > 0 and
            "@" in self.email
        )

    @rx.var
    def step2_valid(self) -> bool:
        """Check if step 2 is complete."""
        return (
            len(self.street) > 0 and
            len(self.city) > 0 and
            len(self.zip_code) == 5
        )

    def next_step(self):
        """Advance to next step."""
        if self.current_step < 3:
            self.current_step += 1

    def prev_step(self):
        """Go back one step."""
        if self.current_step > 1:
            self.current_step -= 1

    def submit_form(self):
        """Submit complete form."""
        # Process form data
        print(f"Submitted: {self.first_name} {self.last_name}")
        # Reset form
        self.current_step = 1


def step1():
    return rx.vstack(
        rx.heading("Step 1: Personal Information"),
        rx.input(
            placeholder="First Name",
            value=MultiStepFormState.first_name,
            on_change=MultiStepFormState.set_first_name,
        ),
        rx.input(
            placeholder="Last Name",
            value=MultiStepFormState.last_name,
            on_change=MultiStepFormState.set_last_name,
        ),
        rx.input(
            placeholder="Email",
            type="email",
            value=MultiStepFormState.email,
            on_change=MultiStepFormState.set_email,
        ),
        rx.button(
            "Next",
            on_click=MultiStepFormState.next_step,
            disabled=~MultiStepFormState.step1_valid,
        ),
    )


def step2():
    return rx.vstack(
        rx.heading("Step 2: Address"),
        rx.input(
            placeholder="Street",
            value=MultiStepFormState.street,
            on_change=MultiStepFormState.set_street,
        ),
        rx.input(
            placeholder="City",
            value=MultiStepFormState.city,
            on_change=MultiStepFormState.set_city,
        ),
        rx.input(
            placeholder="ZIP Code",
            value=MultiStepFormState.zip_code,
            on_change=MultiStepFormState.set_zip_code,
        ),
        rx.hstack(
            rx.button("Back", on_click=MultiStepFormState.prev_step),
            rx.button(
                "Next",
                on_click=MultiStepFormState.next_step,
                disabled=~MultiStepFormState.step2_valid,
            ),
        ),
    )


def step3():
    return rx.vstack(
        rx.heading("Step 3: Preferences"),
        rx.checkbox(
            "Subscribe to newsletter",
            checked=MultiStepFormState.newsletter,
            on_change=MultiStepFormState.set_newsletter,
        ),
        rx.checkbox(
            "Enable notifications",
            checked=MultiStepFormState.notifications,
            on_change=MultiStepFormState.set_notifications,
        ),
        rx.hstack(
            rx.button("Back", on_click=MultiStepFormState.prev_step),
            rx.button("Submit", on_click=MultiStepFormState.submit_form),
        ),
    )


def multi_step_form():
    return rx.container(
        rx.cond(
            MultiStepFormState.current_step == 1,
            step1(),
            rx.cond(
                MultiStepFormState.current_step == 2,
                step2(),
                step3(),
            ),
        ),
    )

Dependent Fields Pattern

class DependentFieldsState(rx.State):
    """Form with dependent/conditional fields."""

    country: str = ""
    state: str = ""
    province: str = ""

    # Available states/provinces by country
    us_states: list[str] = ["California", "New York", "Texas"]
    canada_provinces: list[str] = ["Ontario", "Quebec", "British Columbia"]

    @rx.var
    def show_state_field(self) -> bool:
        """Show state field only for US."""
        return self.country == "United States"

    @rx.var
    def show_province_field(self) -> bool:
        """Show province field only for Canada."""
        return self.country == "Canada"

    @rx.var
    def region_options(self) -> list[str]:
        """Get appropriate region options."""
        if self.country == "United States":
            return self.us_states
        elif self.country == "Canada":
            return self.canada_provinces
        return []


def dependent_form():
    return rx.vstack(
        rx.select(
            ["United States", "Canada", "Other"],
            placeholder="Select Country",
            value=DependentFieldsState.country,
            on_change=DependentFieldsState.set_country,
        ),

        # Conditional US state field
        rx.cond(
            DependentFieldsState.show_state_field,
            rx.select(
                DependentFieldsState.us_states,
                placeholder="Select State",
                value=DependentFieldsState.state,
                on_change=DependentFieldsState.set_state,
            ),
            rx.box(),
        ),

        # Conditional Canada province field
        rx.cond(
            DependentFieldsState.show_province_field,
            rx.select(
                DependentFieldsState.canada_provinces,
                placeholder="Select Province",
                value=DependentFieldsState.province,
                on_change=DependentFieldsState.set_province,
            ),
            rx.box(),
        ),
    )

Data Visualization with Charts

Interactive Dashboard

class DashboardState(rx.State):
    """Dashboard with multiple chart types."""

    sales_data: list[dict] = [
        {"month": "Jan", "sales": 4000, "profit": 2400},
        {"month": "Feb", "sales": 3000, "profit": 1398},
        {"month": "Mar", "sales": 2000, "profit": 9800},
        {"month": "Apr", "sales": 2780, "profit": 3908},
        {"month": "May", "sales": 1890, "profit": 4800},
        {"month": "Jun", "sales": 2390, "profit": 3800},
    ]

    category_data: list[dict] = [
        {"name": "Electronics", "value": 400},
        {"name": "Clothing", "value": 300},
        {"name": "Food", "value": 300},
        {"name": "Books", "value": 200},
    ]


def dashboard():
    return rx.container(
        rx.vstack(
            rx.heading("Sales Dashboard", size="2xl"),

            # Line chart
            rx.box(
                rx.heading("Monthly Sales & Profit", size="lg", mb="2"),
                rx.recharts.line_chart(
                    rx.recharts.line(data_key="sales", stroke="#8884d8"),
                    rx.recharts.line(data_key="profit", stroke="#82ca9d"),
                    rx.recharts.x_axis(data_key="month"),
                    rx.recharts.y_axis(),
                    rx.recharts.legend(),
                    data=DashboardState.sales_data,
                    width="100%",
                    height=300,
                ),
            ),

            # Bar chart
            rx.box(
                rx.heading("Category Distribution", size="lg", mb="2"),
                rx.recharts.bar_chart(
                    rx.recharts.bar(data_key="value", fill="#8884d8"),
                    rx.recharts.x_axis(data_key="name"),
                    rx.recharts.y_axis(),
                    data=DashboardState.category_data,
                    width="100%",
                    height=300,
                ),
            ),

            # Pie chart
            rx.box(
                rx.heading("Market Share", size="lg", mb="2"),
                rx.recharts.pie_chart(
                    rx.recharts.pie(
                        data=DashboardState.category_data,
                        data_key="value",
                        name_key="name",
                        fill="#8884d8",
                    ),
                    rx.recharts.legend(),
                    width="100%",
                    height=300,
                ),
            ),

            spacing="8",
        ),
    )

Database Patterns

DuckDB Integration

import duckdb
import polars as pl


class DBIntegrationState(rx.State):
    """DuckDB database integration."""

    records: list[dict] = []
    filtered_records: list[dict] = []
    search_term: str = ""

    async def load_all_records(self):
        """Load all records from database."""
        conn = duckdb.connect("data/app.duckdb")
        df = conn.execute("SELECT * FROM users").pl()
        self.records = df.to_dicts()
        conn.close()

    async def search_records(self):
        """Search records by term."""
        if not self.search_term:
            self.filtered_records = self.records
            return

        conn = duckdb.connect("data/app.duckdb")
        query = """
            SELECT * FROM users
            WHERE name LIKE ? OR email LIKE ?
        """
        search_pattern = f"%{self.search_term}%"
        df = conn.execute(query, [search_pattern, search_pattern]).pl()
        self.filtered_records = df.to_dicts()
        conn.close()

    async def add_record(self, data: dict):
        """Insert new record."""
        conn = duckdb.connect("data/app.duckdb")
        conn.execute(
            "INSERT INTO users (name, email) VALUES (?, ?)",
            [data["name"], data["email"]]
        )
        conn.close()
        await self.load_all_records()

    async def delete_record(self, user_id: int):
        """Delete record by ID."""
        conn = duckdb.connect("data/app.duckdb")
        conn.execute("DELETE FROM users WHERE id = ?", [user_id])
        conn.close()
        await self.load_all_records()

Polars Data Processing

import polars as pl


class DataProcessingState(rx.State):
    """Polars data processing patterns."""

    raw_data: list[dict] = []
    processed_data: list[dict] = []

    async def process_data(self):
        """Process data using Polars."""
        # Convert to Polars DataFrame
        df = pl.DataFrame(self.raw_data)

        # Example processing pipeline
        processed = (
            df
            .filter(pl.col("amount") > 100)
            .group_by("category")
            .agg([
                pl.col("amount").sum().alias("total"),
                pl.col("amount").mean().alias("average"),
                pl.col("id").count().alias("count"),
            ])
            .sort("total", descending=True)
        )

        self.processed_data = processed.to_dicts()

Advanced Component Patterns

Reusable Data Card

def data_card(
    title: str,
    value: str,
    change: str,
    icon: str,
    color: str = "blue",
) -> rx.Component:
    """Reusable card component for displaying metrics."""
    return rx.box(
        rx.vstack(
            rx.hstack(
                rx.icon(icon, size=32, color=f"{color}.500"),
                rx.spacer(),
                rx.badge(change, color_scheme="green" if "+" in change else "red"),
                width="100%",
            ),
            rx.text(title, font_size="sm", color="gray.600"),
            rx.heading(value, size="2xl", color=f"{color}.600"),
            spacing="2",
            align="start",
        ),
        padding="6",
        border_radius="lg",
        bg="white",
        box_shadow="md",
        width="100%",
    )


def metrics_dashboard():
    return rx.responsive_grid(
        data_card("Total Sales", "$45,231", "+12.5%", "trending_up", "blue"),
        data_card("New Users", "1,234", "+5.2%", "person_add", "green"),
        data_card("Revenue", "$12,345", "+8.1%", "attach_money", "purple"),
        data_card("Orders", "567", "-2.4%", "shopping_cart", "orange"),
        columns=[1, 2, 4],
        spacing="4",
    )

Modal Dialog Pattern

class ModalState(rx.State):
    """Modal dialog state."""

    show_modal: bool = False
    selected_item: dict = {}

    def open_modal(self, item: dict):
        """Open modal with item data."""
        self.selected_item = item
        self.show_modal = True

    def close_modal(self):
        """Close modal."""
        self.show_modal = False
        self.selected_item = {}


def modal_dialog():
    return rx.cond(
        ModalState.show_modal,
        rx.box(
            rx.box(
                rx.vstack(
                    rx.hstack(
                        rx.heading("Item Details"),
                        rx.spacer(),
                        rx.button("×", on_click=ModalState.close_modal),
                        width="100%",
                    ),
                    rx.text(f"Name: {ModalState.selected_item.get('name', '')}"),
                    rx.text(f"Value: {ModalState.selected_item.get('value', '')}"),
                    rx.button("Close", on_click=ModalState.close_modal),
                ),
                bg="white",
                padding="6",
                border_radius="lg",
                max_width="500px",
            ),
            position="fixed",
            top="0",
            left="0",
            width="100vw",
            height="100vh",
            bg="rgba(0,0,0,0.5)",
            display="flex",
            align_items="center",
            justify_content="center",
            z_index="1000",
        ),
        rx.box(),
    )

Performance Optimization

Lazy Loading Pattern

class LazyLoadState(rx.State):
    """Lazy load data as user scrolls."""

    items: list[dict] = []
    page: int = 1
    has_more: bool = True
    is_loading: bool = False

    async def load_more(self):
        """Load next page of data."""
        if self.is_loading or not self.has_more:
            return

        self.is_loading = True

        # Fetch next page (replace with actual API call)
        new_items = await fetch_page(self.page)

        if new_items:
            self.items.extend(new_items)
            self.page += 1
        else:
            self.has_more = False

        self.is_loading = False


def lazy_list():
    return rx.vstack(
        rx.foreach(LazyLoadState.items, lambda item: rx.text(item["name"])),
        rx.cond(
            LazyLoadState.has_more,
            rx.button(
                "Load More",
                on_click=LazyLoadState.load_more,
                disabled=LazyLoadState.is_loading,
            ),
            rx.text("No more items"),
        ),
    )

Debounced Search

import asyncio


class SearchState(rx.State):
    """Debounced search implementation."""

    search_query: str = ""
    search_results: list[dict] = []
    is_searching: bool = False
    _search_task: asyncio.Task = None

    async def debounced_search(self, query: str):
        """Search with 500ms debounce."""
        self.search_query = query

        # Cancel previous search
        if self._search_task and not self._search_task.done():
            self._search_task.cancel()

        # Start new search after delay
        self._search_task = asyncio.create_task(self._perform_search())

    async def _perform_search(self):
        """Perform the actual search after delay."""
        await asyncio.sleep(0.5)  # 500ms debounce

        if not self.search_query:
            self.search_results = []
            return

        self.is_searching = True

        # Perform search (replace with actual search)
        results = await search_api(self.search_query)
        self.search_results = results

        self.is_searching = False


def search_box():
    return rx.vstack(
        rx.input(
            placeholder="Search...",
            value=SearchState.search_query,
            on_change=SearchState.debounced_search,
        ),
        rx.cond(
            SearchState.is_searching,
            rx.spinner(),
            rx.foreach(
                SearchState.search_results,
                lambda r: rx.text(r["title"]),
            ),
        ),
    )