Updating Objects in State

Overview¶

State can hold any kind of value, including dicts and lists. But you shouldn't change objects that you hold in ReactPy state directly. Instead, when you want to update an object, you need to create a new one (or make a copy of an existing one), and then set the state to use that copy.

What's a mutation?¶

To mutate something means to change it after it was created.

Objects and lists in Python are mutable: you can change their contents in place. The mutating operations are usually visible in the code you write — obj["key"] = value, list.append(x), list.pop(), del list[i], d.update(other) — but there are more hiding behind method names that don't announce themselves (list.sort(), list.extend(), list.reverse(), dict.setdefault()).

In ReactPy, treat state as read-only. Every time your code renders, you work with the state that already exists, and you want to cause changes over time based on user input. Leaving all mutation to the setter keeps your code easy to understand. This applies to state in general, not just object state.

Treat state as read-only¶

Consider a form that lets the user change their profile. This handler reaches into the state object and assigns a field directly:

def handle_first_name(event):
    person["firstName"] = event["target"]["value"]   # 🚩 Mutate!
    set_person(person)                                # same object -> ignored

person is the very object ReactPy already holds, so the assignment changes it in place and then hands the same object back. ReactPy compares it against what it already has, finds nothing changed, and skips the render — the field appears frozen while your dict quietly holds the new value.

The fix is to always create a new object for the next state:

def handle_first_name(event):
    set_person({**person, "firstName": event["target"]["value"]})

That is the pattern for every state update in ReactPy: build a new value, pass it to the setter.

A pointer-tracking dot shows the same rule with no form in sight. The handler builds a brand-new position dict on every move:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

@component
def moving_dot():
    position, set_position = use_state({"x": 0, "y": 0})

    def handle_move(event):
        # Replace the whole object: ReactPy never merges a partial update.
        set_position({"x": event["clientX"], "y": event["clientY"]})

    return html.div(
        {
            "onPointerMove": handle_move,
            "style": {
                "position": "relative",
                "width": "100%",
                "height": "180px",
                "background": "#f0f0f0",
            },
        },
        html.div(
            {
                "style": {
                    "position": "absolute",
                    "background": "black",
                    "borderRadius": "50%",
                    "width": "20px",
                    "height": "20px",
                    "left": "-10px",
                    "top": "-10px",
                    "transform": f"translate({position['x']}px, {position['y']}px)",
                }
            }
        ),
    )

1

# TODO

The "onPointerMove" handler is on the grey container, and the dot is positioned from the coordinates it receives. Move the pointer anywhere inside the box and the dot follows. event["clientX"] and event["clientY"] are part of what the client sends for pointer events — verified against a real browser, which reported clientX/clientY matching the synthesized pointer position — so React's pointer and drag demos port across unchanged.

@component
def list_of_parts(parts):
    # Built during this render, never handed out before.
    sorted_parts = sorted(parts, key=lambda p: p["importance"])
    return html.ul(
        [html.li({"key": p["id"]}, p["title"]) for p in sorted_parts]
    )

Copying objects with the spread syntax¶

To update an object, create a new one from the old one so you can change any of its properties. Python has no ... spread operator, but {**obj, "key": value} is the same operation on dicts, and [*items, x] is its twin for lists.

Here the form keeps the other fields intact while replacing one:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

@component
def form():
    person, set_person = use_state(
        {
            "firstName": "Jane",
            "lastName": "Jacobs",
            "email": "jane@example.com",
        }
    )

    def handle_first_name(event):
        # Copy everything, then override just this one field.
        set_person({**person, "firstName": event["target"]["value"]})

    def handle_last_name(event):
        set_person({**person, "lastName": event["target"]["value"]})

    def handle_email(event):
        set_person({**person, "email": event["target"]["value"]})

    return html.div(
        html.input({"value": person["firstName"], "onChange": handle_first_name}),
        html.input({"value": person["lastName"], "onChange": handle_last_name}),
        html.input({"value": person["email"], "onChange": handle_email}),
        html.hr(),
        html.h1(f"Hello, {person['firstName']} {person['lastName']}!"),
        html.a({"href": f"mailto:{person['email']}"}, person["email"]),
    )

1

# TODO

Type in any field and watch the heading update. Each handler spreads the current person into a fresh dict and overrides exactly one key.

rest = {k: v for k, v in obj.items() if k != "drop"}

Using a single event handler for multiple fields¶

Repeating a near-identical handler per field gets tedious. One handler can take the field name:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

@component
def form():
    person, set_person = use_state(
        {"firstName": "Jane", "lastName": "Jacobs", "email": "jane@example.com"}
    )

    # One handler for every field. ReactPy always calls a handler with the
    # event as its single positional argument, so the field name is bound by
    # the lambdas below rather than delivered by the client.
    def handle_change(field, event):
        set_person({**person, field: event["target"]["value"]})

    return html.div(
        html.input(
            {
                "value": person["firstName"],
                "onChange": lambda event: handle_change("firstName", event),
            }
        ),
        html.input(
            {
                "value": person["lastName"],
                "onChange": lambda event: handle_change("lastName", event),
            }
        ),
        html.input(
            {
                "value": person["email"],
                "onChange": lambda event: handle_change("email", event),
            }
        ),
        html.hr(),
        html.h1(f"Hello, {person['firstName']} {person['lastName']}!"),
    )

1

# TODO

Note how the field name is supplied by the lambda. ReactPy invokes every event handler with the event as its single positional argument — verified, a handler declaring two required parameters fails with TypeError: ... missing 1 required positional argument: 'event'. There is no e.target.name to read either, because the client does not send DOM attributes; any extra context has to be bound on the Python side.

Updating a nested object¶

State often contains nested objects. To update a deeply nested value, copy the object all the way up from where the change happens.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

@component
def form():
    person, set_person = use_state(
        {
            "firstName": "Jane",
            "lastName": "Jacobs",
            "email": "jane@example.com",
            "shippingAddress": {
                "street": "123 Maple Street",
                "city": "Pretendville",
            },
        }
    )

    def handle_city(event):
        address = {**person["shippingAddress"], "city": event["target"]["value"]}
        set_person({**person, "shippingAddress": address})

    return html.div(
        html.label(
            "City: ",
            html.input(
                {
                    "value": person["shippingAddress"]["city"],
                    "onChange": handle_city,
                }
            ),
        ),
        html.h1(person["firstName"]),
        html.p(person["shippingAddress"]["street"]),
        html.p(person["shippingAddress"]["city"]),
    )

1

# TODO

Two copies are required:

1. Copy person["shippingAddress"] with the new "city".
2. Copy person, replacing "shippingAddress" with that new dict.

Writing person["shippingAddress"]["city"] = ... would mutate the nested dict in place. Because that nested dict is the same object the previous state still refers to, the change is invisible to ReactPy's comparison and the update is dropped.

person = {"name": "Jane", "theme": {"background": "white"}}
copy = {**person}

import copy

set_people(copy.deepcopy(people))

Writing concise update logic¶

React's docs reach for Immer here, which records your mutations through a proxy and turns them into copies. ReactPy has no Immer and no equivalent. There is no proxy layer, so nothing could observe your mutations, and there is no use_immer to import.

What you have instead:

• Dict and list unpacking — {**obj, "k": v}, [*items, x]. This covers the overwhelming majority of updates and is what every example above uses.
• copy.deepcopy — for the rare shape too deep to copy by hand.
• use_reducer — does not shorten updates, but moves them out of the component so their verbosity costs you less. See Extracting State Logic into a Reducer.

Resist building your own Immer. A proxy that logs mutations would have to run on the server, after a websocket round trip, which is not the problem Immer solves in the browser. If update logic feels genuinely painful, that usually means the state shape is wrong — see Choosing the State Structure.

Recap¶

• Treat everything ReactPy hands you as state or props as read-only: never assign into it, never call a mutating method on it.
• Build a new object with {**old, ...} and pass that to the setter.
• Mutating in place and passing the same object back is silently dropped — ReactPy compares the new value with the old and schedules no render when they are equal. Nothing in the browser will tell you.
• Copying is shallow at every level; copy all the way up from the field that changed, or use copy.deepcopy.
• Mutating a value you created during this render is fine.
• There is no Immer in ReactPy; use dict and list unpacking, or restructure the state.