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,


...