Skip to main content
An action is what happens when a user interacts. Click a button, submit a form, change a slider: any interaction that matters can carry an action. Actions are how state gets updated, how servers get called, and how the UI gives feedback. Every interactive component exposes event handlers (on_click, on_change, on_submit) that accept an action, a list of actions, or None. When the event fires, the action runs. For the most common case, syncing an interactive component’s value to state, the name prop handles it automatically. Input(name="query") writes to the query key on every keystroke without any explicit action. You reach for actions when you need side effects beyond syncing: showing a toast, calling your server, updating multiple keys at once, or running logic conditionally.

​
Two families

Prefab draws a clear line between two kinds of actions. Client actions run entirely in the browser. They execute instantly, require no network, and always succeed. SetState, ToggleState, AppendState, ShowToast, OpenLink, SetInterval: these are your tools for managing UI state and giving immediate feedback. From the user’s perspective, they’re instantaneous. Server actions cross a network boundary. CallTool invokes an MCP tool on your server. Fetch makes an HTTP request. They’re asynchronous: they take time and they can fail. The UI needs to account for both the happy path and errors. Most real interactions use both. A “Save” button typically sets a loading flag (client, instant), calls the server (server, async), then shows success or failure feedback (client, instant based on the outcome). The split is a design constraint that keeps the UI responsive and makes the code predictable.
Client actionsPurpose
SetStateSet a state key to a value
ToggleStateFlip a boolean state key
AppendStateAdd an item to a state array
PopStateRemove an item from a state array by index
ShowToastDisplay a brief notification
OpenLinkOpen a URL
SetIntervalSchedule an action to repeat on a timer
CallHandlerInvoke a developer-registered JavaScript handler
Server actionsPurpose
CallToolCall an MCP tool; result available as $result in on_success
FetchMake an HTTP request; result available as $result in on_success
SendMessageSend a message to the conversation (MCP hosts only)
UpdateContextPush structured context to the model (MCP hosts only)

​
The $event variable

When an interaction fires, the component emits a value: the slider’s current position, the input’s current text, the checkbox’s checked state. That value is available inside action arguments as $event. Most of the time you don’t need $event directly, because the name prop already syncs the component’s value to state automatically. Where $event becomes useful is in actions that need to reference the emitted value as part of a larger operation, like writing it to a different key, sending it to the server, or using it in a computation: 
from prefab_ui.actions import SetState
from prefab_ui.actions.mcp import CallTool

# Write the emitted value to a different state key
Slider(name="volume", on_change=SetState("last_changed_volume", "{{ $event }}"))

# Pass the emitted value to a server call
Input(on_change=CallTool("search", arguments={"q": "{{ $event }}"}))
The Expressions guide has the full table of what each component emits.

​
Chaining actions

A single interaction often needs to do more than one thing. An “Add” button might append an item to a list and then clear the input field. A “Save” button might set a loading flag and then call the server. To run multiple actions from one event, pass a list. The actions execute in order, and if any action fails, execution stops at that point so a failed server call won’t silently proceed to the cleanup steps. Here’s a crew list where the “Add” button chains two actions: AppendState pushes the input value onto the array, then SetState clears the input field. Both execute before the next render, so the user sees the item appear and the field reset simultaneously. The list syntax [action1, action2, ...] works with any event handler: on_click, on_change, on_submit.

​
Callbacks: on_success and on_error

Action lists handle the setup: things to do before or alongside an interaction. Callbacks handle the outcomes: things to do after an async action completes. Every action supports on_success and on_error. They fire after the action resolves, with the outcome determining which branch runs. Both accept a single action or a list. 
from prefab_ui.actions import SetState, ShowToast
from prefab_ui.actions.mcp import CallTool
from prefab_ui.rx import RESULT

Button(
    "Save",
    on_click=CallTool(
        "save_record",
        arguments={"data": Rx("form")},
        on_success=[
            SetState("result", RESULT),
            ShowToast("Saved!", variant="success"),
        ],
        on_error=ShowToast("{{ $error }}", variant="error"),
    ),
)
$result is available inside on_success callbacks; it holds the return value of the action that just completed. $error is available inside on_error callbacks; it holds the error message from the failed action. These are a matched pair: each exists only within its respective callback scope. Callbacks can themselves have callbacks, making it possible to chain dependent server calls: the result of the first determines what to fetch next. 
CallTool(
    "get_user",
    arguments={"id": Rx("user_id")},
    on_success=[
        SetState("user", RESULT),
        CallTool(
            "get_permissions",
            arguments={"role": "{{ user.role }}"},
            on_success=SetState("permissions", RESULT),
        ),
    ],
)

​
Custom handlers

CallHandler invokes a developer-registered JavaScript function client-side. Where CallTool crosses the network to your server, CallHandler runs instantly in the browser — useful for state transformations that are too complex for expressions but don’t need server involvement. Register handlers via js_actions on PrefabApp, then reference them by name: 
from prefab_ui.actions import CallHandler

Slider(name="infra", on_change=CallHandler("constrainBudget"))
The handler receives {state, event, arguments} and returns state updates to merge. See Custom Handlers for the full API, including custom pipes.

​
Common patterns

​
Loading state

The combination of lists and callbacks is what makes loading state clean. Set a flag before the server call in the list; clear it in both callback branches so it always resolves, whether the call succeeds or fails: 
from prefab_ui.rx import Rx

saving = Rx("saving")

Button(
    saving.then("Saving...", "Save"),
    disabled=saving,
    on_click=[
        SetState("saving", True),
        CallTool(
            "save",
            arguments={"data": Rx("form")},
            on_success=[
                SetState("saving", False),
                ShowToast("Saved!", variant="success"),
            ],
            on_error=[
                SetState("saving", False),
                ShowToast("{{ $error }}", variant="error"),
            ],
        ),
    ],
)
The button label switches and disables while the call is in flight. Both branches clear the flag, so the button always returns to its normal state.

​
Populating results

For search and filter patterns, use RESULT in an on_success callback to write the tool’s response directly into state, then have a ForEach or Slot display it: 
from prefab_ui.actions import SetState
from prefab_ui.actions.mcp import CallTool
from prefab_ui.components import Button, Column, ForEach, Input, Text
from prefab_ui.rx import RESULT

with Column(gap=3):
    query = Input(name="q", placeholder="Search...")
    Button(
        "Search",
        on_click=CallTool(
            "search",
            arguments={"q": query.rx},
            on_success=SetState("results", RESULT),
        ),
    )
    with ForEach("results"):
        Text("{{ name }}")
When the tool returns, RESULT holds the response data. SetState writes it to results, and the ForEach re-renders with whatever came back.

​
Optimistic updates

For interactions where you’re confident the server will succeed, update state immediately and let the server confirm in the background. Revert on failure: 
with ForEach("todos"):
    Checkbox(
        name="todos.{{ $index }}.done",
        on_change=[
            SetState("todos.{{ $index }}.done", "{{ $event }}"),
            CallTool(
                "persist_todo",
                arguments={"id": "{{ $item.id }}", "done": "{{ $event }}"},
                on_error=[
                    SetState("todos.{{ $index }}.done", "{{ !$event }}"),
                    ShowToast("Failed to save", variant="error"),
                ],
            ),
        ],
    )
The checkbox updates instantly. If the server fails, the on_error branch flips it back and shows a toast.