Events Overview
Events are composed of two parts: Event Triggers and Event Handlers.
- Events Handlers are how the State of a Reflex application is updated. They are triggered by user interactions with the UI, such as clicking a button or hovering over an element. Events can also be triggered by the page loading or by other events.
- Event triggers are component props that create an event to be sent to an event handler. Each component supports a set of events triggers. They are described in each component's documentation in the event trigger section.
Example
Lets take a look at an example below. Try mousing over the heading to change the word.
Welcome
In this example, the heading component has the event trigger, on_mouse_over.
Whenever the user hovers over the heading, the next_word event handler will be called to cycle the word. Once the handler returns, the UI will be updated to reflect the new state.
Adding the @rx.event decorator above the event handler is strongly recommended. This decorator enables proper static type checking, which ensures event handlers receive the correct number and types of arguments.
By default, every public method of a state (one whose name does not start with _) is treated as an event handler, whether or not it is decorated. To make @rx.event mandatory and keep undecorated public methods as plain Python helpers, enable state_explicit_event_handlers in rxconfig.py:
config = rx.Config(
app_name="my_app",
state_explicit_event_handlers=True,
)This also applies to states from third-party packages, so they must decorate their event handlers for the option to be usable in your app.
The option is applied when a state class is created. reflex run loads rxconfig.py before it imports your app. Other entry points that import your state modules first, such as a test suite or an ASGI server pointed at the app module, must set the REFLEX_STATE_EXPLICIT_EVENT_HANDLERS environment variable instead.
A call such as State.delete(item.id) in page code also needs the decorator. Without it, State.delete is a plain function, so Python calls it while the page compiles.
What's in this section?
In the event section of the documentation, you will explore the different types of events supported by Reflex, along with the different ways to call them.