Click and it changes: State and events

Before any explanation, let's click something. Press the button below and the number goes up by 1. By the end of this lesson, you'll be able to explain exactly how these dozen or so lines of code work.

import reflex as rx


class CounterState(rx.State):
    count: int = 0

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


def counter_increment():
    return rx.hstack(
        rx.heading(CounterState.count, as_="h2"),
        rx.button("Increment", on_click=CounterState.increment),
    )

The code has three parts.

When you click the button, increment runs on the server. Once count changes, Reflex automatically redraws just the parts of the page that use it. You never write a single line of code that updates the page directly.

1-1. State: where changing data lives (2 min)

Apps have data that changes over time: the number in a counter, whether you're logged in, the items in a shopping cart. In Reflex, you keep this kind of data in a State class.

• Create a class that inherits from rx.State and declare variables inside it. These variables are called Vars (state vars).
• Every Var needs a type annotation (count: int), and you can give it a default value (= 0).

To use a Var in your UI, refer to it through the class name, like MyState.count. You can pass it as a child or as a prop value.

class MyState(rx.State):
    count: int = 0
    color: str = "red"


def counter():
    return rx.hstack(
        # The heading `color` prop is set to the `color` var in MyState.
        rx.heading("Count: ", as_="h2", color=MyState.color),
        # The `count` var in `MyState` is passed as a child to the heading component.
        rx.heading(MyState.count, as_="h2"),
    )

You can use the same Var in as many components as you like. When its value changes, every place that uses it updates together.

1-2. Event handlers and @rx.event (2 min)

Methods on a State that change its data are called event handlers. Special props on components, such as on_click, are called event triggers. Connect a trigger to a handler, and your page responds to what the user does.

1. The user clicks a button (an event trigger fires).
2. The connected event handler runs on the server and changes the State.
3. Reflex sends the updated State to the browser, and the page is redrawn.

We recommend always putting @rx.event above your handlers. With this decorator, your editor and type checker can verify how many arguments a handler takes and of what types, so you catch mistakes early.

1-3. Event handlers with arguments (2 min)

Like regular functions, handlers can take arguments. Let's build an "add 1" and an "add 5" button with a single handler.

class CounterState2(rx.State):
    count: int = 0

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


def counter_variable():
    return rx.hstack(
        rx.heading(CounterState2.count, as_="h2"),
        rx.button("Increment by 1", on_click=lambda: CounterState2.increment(1)),
        rx.button("Increment by 5", on_click=lambda: CounterState2.increment(5)),
    )

• This example wraps the call in a lambda, as in lambda: CounterState2.increment(1), to make the intent clear: "on click, call it with 1."
• Writing on_click=CounterState2.increment(1) directly works exactly the same way. It doesn't run the handler right away; it only creates the event information "on click, run this with amount=1." The handler code runs on the server when the button is clicked.

1-4. When the trigger passes a value: on_blur (2 min)

on_click doesn't pass any value to its handler, but some triggers do. on_blur fires when the input loses focus (when you click somewhere else or press Tab), and it passes the text you typed to the handler.

class TextState(rx.State):
    text: str = ""

    @rx.event
    def update_text(self, new_text: str):
        self.text = new_text


def text_input():
    return rx.vstack(
        rx.heading(TextState.text, as_="h2"),
        rx.input(default_value=TextState.text, on_blur=TextState.update_text),
    )

Exercises

1. Add a decrement handler to CounterState and make a button that lowers the number by 1.
2. Add a "Reset" button to counter_variable that sets count back to 0. Could you do it with a handler that takes an argument?
3. Try on_change instead of on_blur. Now the heading updates with every keystroke.

Checkpoint

• You can explain what State, a Var, an event handler and an event trigger each are.
• You can refer to a Var in your UI as ClassName.var_name.
• You know why passing an argument in on_click doesn't run the handler right away.