Decentralized Event Handlers

Decentralized event handlers allow you to define event handlers outside of state classes, providing more flexible code organization. This feature was introduced in Reflex v0.7.10 and enables a more modular approach to event handling.

With decentralized event handlers, you can:

• Organize event handlers by feature rather than by state class
• Separate UI logic from state management
• Create more maintainable and scalable applications

To create a decentralized event handler, use the @rx.event decorator on a function that takes a state instance as its first parameter:

In this example:

1. We define a MyState class with a count variable
2. We create a decentralized event handler increment that takes a MyState instance as its first parameter
3. We use the event handler in buttons, passing different amounts to increment by

Here's a comparison between traditional event handlers defined within state classes and decentralized event handlers:

# Traditional event handler within a state class
class TraditionalState(rx.State):
    count: int = 0

    @rx.event
    def increment(self, amount: int = 1):
        self.count += amount


# Usage in components
rx.button("Increment", on_click=TraditionalState.increment(5))


# Decentralized event handler outside the state class
class DecentralizedState(rx.State):
    count: int = 0


@rx.event
def increment(state: DecentralizedState, amount: int = 1):
    state.count += amount


# Usage in components
rx.button("Increment", on_click=increment(5))

Key differences:

• Traditional event handlers use self to reference the state instance
• Decentralized event handlers explicitly take a state instance as the first parameter
• Both approaches use the same syntax for triggering events in components
• Both can be decorated with @rx.event respectively

Decentralized event handlers are particularly useful in these scenarios:

1. Large applications with many event handlers that benefit from better organization
2. Feature-based organization where you want to group related event handlers together
3. Separation of concerns when you want to keep state definitions clean and focused

Always use proper type annotations for your state parameter and any additional parameters:

@rx.event
def update_user(state: UserState, name: str, age: int):
    state.name = name
    state.age = age

Follow these naming conventions for clarity:

1. Use descriptive names that indicate the action being performed
2. Use the state class name as the type annotation for the first parameter
3. Name the state parameter consistently across your codebase (e.g., always use state or the first letter of the state class)

Consider these approaches for organizing decentralized event handlers:

1. Group related event handlers in the same file
2. Place event handlers near the state classes they modify
3. For larger applications, create a dedicated events directory with files organized by feature

# Example organization in a larger application
# events/user_events.py
@rx.event
def update_user(state: UserState, name: str, age: int):
    state.name = name
    state.age = age


@rx.event
def delete_user(state: UserState):
    state.name = ""
    state.age = 0

Decentralized event handlers work seamlessly with other Reflex event features:

# Background event
@rx.event(background=True)
async def long_running_task(state: AppState):
    # Long-running task implementation
    pass


# Event chaining
@rx.event
def process_form(state: FormState, data: dict):
    # Process form data
    return validate_data  # Chain to another event

A function decorated with @rx.event whose first parameter is not a state is a stateless event handler. It is registered like any other handler, so it can be used as an event trigger and awaited from other handlers, but it runs without a state and takes no state lock of its own. Triggered from the frontend, it runs at once and the client's other events do not wait behind it; awaited from a handler, it runs inline under whatever lock that handler holds.

class PortfolioState(rx.State):
    price: float = 0.0

    @rx.event
    def show_price(self, price: float):
        self.price = price


@rx.event
async def refresh_quote(symbol: str):
    # No state lock is held while the request is in flight.
    yield PortfolioState.show_price(await price_service.quote(symbol))


def quote_button():
    return rx.button("Refresh", on_click=refresh_quote("ACME"))

Events a stateless handler yields or returns run against the state of the client that triggered it, so refresh_quote fetches the quote with no lock held and then hands the result to PortfolioState like any chained event. Without the decorator, refresh_quote would be a plain function that cannot be used as a trigger. Awaiting a stateless handler from another handler runs it inline, so call external services from a background task or from a stateless trigger like this one, never from inside async with self.