Step Types
A Form is a Python script that calls run(steps). The runtime loops through each step: render → wait for user input → advance. There are five step types that cover every UI pattern you'll need.
steps— a list mixing any of the five step types belowstate— optional initial values that pre-fill widgetshide_steps— hides the step counter shown at the top- Returns a dict with all widget values, keyed by each widget's
key=
Put all steps in a single run() call. State is shared across steps within one call, and the Back button only works within a single call. Multiple run() calls are isolated sessions — state is lost between them.
1. Static page
A plain list of widgets. Renders the same content every time — use when nothing needs to change based on previous input.
2. Reactive page
A function that returns a list of widgets. Re-executes on every user interaction (every keystroke, every click). Use for dynamic content, conditional fields, and live validation.
Never put side effects in a reactive page. DB writes, API calls, and send_task would run on every keystroke. Use a computation step for those.
3. Reactive page with custom buttons
Return a (widgets, buttons) tuple to replace the default Next/Back with your own buttons. When a button is clicked, state[key] is set to True (boolean) and the function re-executes.
Button(label, key=None)—keydefaults to the label if omittedstate[key]is alwaysTrue(boolean) when a button is clicked — not a string- Returning
Nonefrom a button-handling branch advances the form silently NextButton()andBackButton()are added automatically; only instantiate them explicitly when mixing them with custom buttons:[Button("Save draft"), NextButton()]ExitButton()terminates the process viasys.exit(0)— use for Cancel flows
4. Computation step
A function with no return value. Runs exactly once when the user navigates through it. No UI is shown. This is the correct place for all side effects: database writes, sending emails, calling APIs, dispatching tasks.
5. Generator step
A function that yields lists of widgets. Use for progress bars or status updates during long operations. Each yield replaces the previous UI — no user interaction is possible between yields. Only output widgets make sense here (ProgressOutput, MarkdownOutput, HtmlOutput).
For flows that upload files and process them in later steps, prefer a Page (see the Pages guide).
Live Validation
Any widget accepts errors: list[str]. Set it inside a reactive page. Widgets with errors block the Next button.
State
State is a dict shared across all steps within one run() call.
state["missing_key"]returnsNone— noKeyError(state is a dict subclass)- Widget values are stored under their
key=parameter - Computation steps can write to state:
state["id"] = record["id"]
Tasks in Forms
Forms receive tasks via get_tasks(). Use the with task: context manager — it auto-completes the task on success and leaves it open if an exception is raised.
task["key"]— access payload fieldstask.complete()— mark as done manually (not needed insidewith task:)
Never use get_trigger_task() in a Form — that function is Tasklet-only. Forms always use get_tasks().
Common Mistakes
| Mistake | Why it's wrong | Correct approach |
|---|---|---|
Multiple run() calls for a multi-step flow | State is lost between calls, no Back | Single run([step1, step2, ...]) |
| Side effects inside a reactive page | Runs on every keystroke | Move to a computation step (no return) |
get_trigger_task() in a Form | Forms don't have trigger tasks | get_tasks() |
No key= on widgets | Auto-generated keys break on reorder | Always set an explicit key= |
state["btn"] == "btn" | Button sets boolean True, not a string | if state.get("btn"): |
| Input widgets inside a generator step | No user interaction during yield | Output widgets only (MarkdownOutput, ProgressOutput, HtmlOutput) |