Adding Interactivity#
What You’ll Learn
Section 1: Responding to Events#
ReactPy lets you add event handlers to your parts of the interface. This means that you can define synchronous or asynchronous functions that are triggered when a particular user interaction occurs like clicking, hovering, focusing on form inputs, and more.
from reactpy import component, html, run
@component
def PrintButton(display_text, message_text):
def handle_event(event):
print(message_text)
return html.button({"on_click": handle_event}, display_text)
@component
def App():
return html.div(
PrintButton("Play", "Playing"),
PrintButton("Pause", "Paused"),
)
run(App)
It may feel weird to define a function within a function like this, but doing so allows
the handle_event function to access information from within the scope of the
component. That’s important if you want to use any arguments that may have been passed
your component in the handler.
Section 2: Components with State#
Components often need to change what’s on the screen as a result of an interaction. For
example, typing into the form should update the input field, clicking a “Comment” button
should bring up a text input field, clicking “Buy” should put a product in the shopping
cart. Components need to “remember” things like the current input value, the current
image, the shopping cart. In ReactPy, this kind of component-specific memory is created and
updated with a “hook” called use_state() that creates a state variable and
state setter respectively:
import json
from pathlib import Path
from reactpy import component, hooks, html, run
HERE = Path(__file__)
DATA_PATH = HERE.parent / "data.json"
sculpture_data = json.loads(DATA_PATH.read_text())
@component
def Gallery():
index, set_index = hooks.use_state(0)
def handle_click(event):
set_index(index + 1)
bounded_index = index % len(sculpture_data)
sculpture = sculpture_data[bounded_index]
alt = sculpture["alt"]
artist = sculpture["artist"]
description = sculpture["description"]
name = sculpture["name"]
url = sculpture["url"]
return html.div(
html.button({"on_click": handle_click}, "Next"),
html.h2(name, " by ", artist),
html.p(f"({bounded_index + 1} of {len(sculpture_data)})"),
html.img({"src": url, "alt": alt, "style": {"height": "200px"}}),
html.p(description),
)
run(Gallery)
[
{
"name": "Homenaje a la Neurocirugía",
"artist": "Marta Colvin Andrade",
"description": "Although Colvin is predominantly known for abstract themes that allude to pre-Hispanic symbols, this gigantic sculpture, an homage to neurosurgery, is one of her most recognizable public art pieces.",
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/2/22/Homenaje_a_la_Neurocirug%C3%ADa%2C_Instituto_de_Neurocirug%C3%ADa%2C_Providencia%2C_Santiago_20200106_02.jpg/1024px-Homenaje_a_la_Neurocirug%C3%ADa%2C_Instituto_de_Neurocirug%C3%ADa%2C_Providencia%2C_Santiago_20200106_02.jpg",
"alt": "A bronze statue of two crossed hands delicately holding a human brain in their fingertips."
},
{
"name": "Eternal Presence",
"artist": "John Woodrow Wilson",
"description": "Wilson was known for his preoccupation with equality, social justice, as well as the essential and spiritual qualities of humankind. This massive (7ft. or 2,13m) bronze represents what he described as \"a symbolic Black presence infused with a sense of universal humanity.\"",
"url": "https://upload.wikimedia.org/wikipedia/commons/6/6f/Chicago%2C_Illinois_Eternal_Silence1_crop.jpg",
"alt": "The sculpture depicting a human head seems ever-present and solemn. It radiates calm and serenity."
},
{
"name": "Moai",
"artist": "Unknown Artist",
"description": "Located on the Easter Island, there are 1,000 moai, or extant monumental statues, created by the early Rapa Nui people, which some believe represented deified ancestors.",
"url": "https://upload.wikimedia.org/wikipedia/commons/5/50/AhuTongariki.JPG",
"alt": "Three monumental stone busts with the heads that are disproportionately large with somber faces."
},
{
"name": "Blue Nana",
"artist": "Niki de Saint Phalle",
"description": "The Nanas are triumphant creatures, symbols of femininity and maternity. Initially, Saint Phalle used fabric and found objects for the Nanas, and later on introduced polyester to achieve a more vibrant effect.",
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c8/Blue_Nana_-_panoramio.jpg/1024px-Blue_Nana_-_panoramio.jpg",
"alt": "A large mosaic sculpture of a whimsical dancing female figure in a colorful costume emanating joy."
},
{
"name": "Cavaliere",
"artist": "Lamidi Olonade Fakeye",
"description": "Descended from four generations of woodcarvers, Fakeye's work blended traditional and contemporary Yoruba themes.",
"url": "https://upload.wikimedia.org/wikipedia/commons/3/34/Nigeria%2C_lamidi_olonade_fakeye%2C_cavaliere%2C_1992.jpg",
"alt": "An intricate wood sculpture of a warrior with a focused face on a horse adorned with patterns."
},
{
"name": "Big Bellies",
"artist": "Alina Szapocznikow",
"description": "Szapocznikow is known for her sculptures of the fragmented body as a metaphor for the fragility and impermanence of youth and beauty. This sculpture depicts two very realistic large bellies stacked on top of each other, each around five feet (1,5m) tall.",
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/9/92/KMM_Szapocznikow.JPG/200px-KMM_Szapocznikow.JPG",
"alt": "The sculpture reminds a cascade of folds, quite different from bellies in classical sculptures."
},
{
"name": "Terracotta Army",
"artist": "Unknown Artist",
"description": "The Terracotta Army is a collection of terracotta sculptures depicting the armies of Qin Shi Huang, the first Emperor of China. The army consisted of more than 8,000 soldiers, 130 chariots with 520 horses, and 150 cavalry horses.",
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/9/9a/2015-09-22-081415_-_Terrakotta-Armee%2C_Grosse_Halle.jpg/1920px-2015-09-22-081415_-_Terrakotta-Armee%2C_Grosse_Halle.jpg",
"alt": "12 terracotta sculptures of solemn warriors, each with a unique facial expression and armor."
},
{
"name": "Lunar Landscape",
"artist": "Louise Nevelson",
"description": "Nevelson was known for scavenging objects from New York City debris, which she would later assemble into monumental constructions. In this one, she used disparate parts like a bedpost, juggling pin, and seat fragment, nailing and gluing them into boxes that reflect the influence of Cubism’s geometric abstraction of space and form.",
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/7/72/1999-3-A--J_s.jpg/220px-1999-3-A--J_s.jpg",
"alt": "A black matte sculpture where the individual elements are initially indistinguishable."
},
{
"name": "Aureole",
"artist": "Ranjani Shettar",
"description": "Shettar merges the traditional and the modern, the natural and the industrial. Her art focuses on the relationship between man and nature. Her work was described as compelling both abstractly and figuratively, gravity defying, and a \"fine synthesis of unlikely materials.\"",
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/5/50/Shettar-_5854-sm_%285132866765%29.jpg/399px-Shettar-_5854-sm_%285132866765%29.jpg",
"alt": "A pale wire-like sculpture mounted on concrete wall and descending on the floor. It appears light."
},
{
"name": "Hippos",
"artist": "Taipei Zoo",
"description": "The Taipei Zoo commissioned a Hippo Square featuring submerged hippos at play.",
"url": "https://upload.wikimedia.org/wikipedia/commons/thumb/e/e3/Hippo_sculpture_Taipei_Zoo_20543.jpg/250px-Hippo_sculpture_Taipei_Zoo_20543.jpg",
"alt": "A group of bronze hippo sculptures emerging from the sett sidewalk as if they were swimming."
}
]
In ReactPy, use_state, as well as any other function whose name starts with use, is
called a “hook”. These are special functions that should only be called while ReactPy is
rendering. They let you “hook into” the different
capabilities of ReactPy’s components of which use_state is just one (well get into the
other later).
Section 3: State as a Snapshot#
As we learned earlier, state setters behave a little differently than you might expect at first glance. Instead of updating your current handle on the setter’s corresponding variable, it schedules a re-render of the component which owns the state.
count, set_count = use_state(0)
print(count) # prints: 0
set_count(count + 1) # schedule a re-render where count is 1
print(count) # still prints: 0
This behavior of ReactPy means that each render of a component is like taking a snapshot of the UI based on the component’s state at that time. Treating state in this way can help reduce subtle bugs. For instance, in the code below there’s a simple chat app with a message input and recipient selector. The catch is that the message actually gets sent 5 seconds after the “Send” button is clicked. So what would happen if we changed the recipient between the time the “Send” button was clicked and the moment the message is actually sent?
import asyncio
from reactpy import component, event, html, run, use_state
@component
def App():
recipient, set_recipient = use_state("Alice")
message, set_message = use_state("")
@event(prevent_default=True)
async def handle_submit(event):
set_message("")
print("About to send message...")
await asyncio.sleep(5)
print(f"Sent '{message}' to {recipient}")
return html.form(
{"on_submit": handle_submit, "style": {"display": "inline-grid"}},
html.label(
{},
"To: ",
html.select(
{
"value": recipient,
"on_change": lambda event: set_recipient(event["target"]["value"]),
},
html.option({"value": "Alice"}, "Alice"),
html.option({"value": "Bob"}, "Bob"),
),
),
html.input(
{
"type": "text",
"placeholder": "Your message...",
"value": message,
"on_change": lambda event: set_message(event["target"]["value"]),
}
),
html.button({"type": "submit"}, "Send"),
)
run(App)
As it turns out, changing the message recipient after pressing send does not change where the message ultimately goes. However, one could imagine a bug where the recipient of a message is determined at the time the message is sent rather than at the time the “Send” button it clicked. Thus changing the recipient after pressing send would change where the message got sent.
In many cases, ReactPy avoids this class of bug entirely because it treats state as a snapshot.
Section 4: Multiple State Updates#
As we saw in an earlier example, Setting State Triggers Renders. In other words,
changes to state only take effect in the next render, not in the current one. Further,
changes to state are batched, calling a particular state setter 3 times won’t trigger 3
renders, it will only trigger 1. This means that multiple state assignments are batched
- so long as the event handler is synchronous (i.e. the event handler is not an
async function), ReactPy waits until all the code in an event handler has run before
processing state and starting the next render:
from reactpy import component, html, run, use_state
@component
def ColorButton():
color, set_color = use_state("gray")
def handle_click(event):
set_color("orange")
set_color("pink")
set_color("blue")
def handle_reset(event):
set_color("gray")
return html.div(
html.button(
{"on_click": handle_click, "style": {"background_color": color}},
"Set Color",
),
html.button(
{"on_click": handle_reset, "style": {"background_color": color}}, "Reset"
),
)
run(ColorButton)
Sometimes though, you need to update a state variable more than once before the next
render. In these cases, instead of having updates batched, you instead want them to be
applied incrementally. That is, the next update can be made to depend on the prior one.
To accomplish this, instead of passing the next state value directly (e.g.
set_state(new_state)), we may pass an “updater function” of the form
compute_new_state(old_state) to the state setter (e.g.
set_state(compute_new_state)):
from reactpy import component, html, run, use_state
def increment(old_number):
new_number = old_number + 1
return new_number
@component
def Counter():
number, set_number = use_state(0)
def handle_click(event):
set_number(increment)
set_number(increment)
set_number(increment)
return html.div(
html.h1(number),
html.button({"on_click": handle_click}, "Increment"),
)
run(Counter)
Section 5: Dangers of Mutability#
While state can hold any type of value, you should be careful to avoid directly modifying objects that you declare as state with ReactPy. In other words, you must not “mutate” values which are held as state. Rather, to change these values you should use new ones or create copies.
This is because ReactPy does not understand that when a value is mutated, it may have changed. As a result, mutating values will not trigger re-renders. Thus, you must be careful to avoid mutation whenever you want ReactPy to re-render a component. For example, instead of mutating dictionaries to update their items you should instead create a copy that contains the desired changes:
from reactpy import component, html, run, use_state
@component
def Form():
person, set_person = use_state(
{
"first_name": "Barbara",
"last_name": "Hepworth",
"email": "bhepworth@sculpture.com",
}
)
def handle_first_name_change(event):
set_person({**person, "first_name": event["target"]["value"]})
def handle_last_name_change(event):
set_person({**person, "last_name": event["target"]["value"]})
def handle_email_change(event):
set_person({**person, "email": event["target"]["value"]})
return html.div(
html.label(
"First name: ",
html.input(
{"value": person["first_name"], "on_change": handle_first_name_change}
),
),
html.label(
"Last name: ",
html.input(
{"value": person["last_name"], "on_change": handle_last_name_change}
),
),
html.label(
"Email: ",
html.input({"value": person["email"], "on_change": handle_email_change}),
),
html.p(f"{person['first_name']} {person['last_name']} {person['email']}"),
)
run(Form)