;
};
State is client-side data that your UI can read and write. Components display state values, actions change them, and updates are instant — no server round-trip needed.
## Setting Up State
Pass initial state to `PrefabApp` via the `state` parameter. Any component in your UI can then read them through `Rx()` references or template expressions:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Slider, Muted, Column
from prefab_ui.rx import Rx
brightness = Rx("brightness")
with Column(gap=3):
Slider(name="brightness", min=0, max=100)
Muted(f"Brightness: {brightness}%")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-3",
"type": "Column",
"children": [
{
"name": "brightness",
"type": "Slider",
"min": 0.0,
"max": 100.0,
"disabled": false,
"size": "default"
},
{"content": "Brightness: {{ brightness }}%", "type": "Muted"}
]
}
}
```
Drag the slider — the text updates instantly. The Slider has `name="brightness"`, which means it automatically reads from and writes to the `brightness` state key. Most form controls (Input, Checkbox, Switch, Select, etc.) support this `name` prop for automatic state binding.
For MCP tools, you can also provide initial state through `AppResult.state`:
```python AppResult State theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui import AppResult
@mcp.tool()
async def settings() -> AppResult:
return AppResult(
view=...,
state={"volume": 75, "muted": False},
)
```
## SetState
`SetState` explicitly sets a state key to a value. Both arguments are required — the key and the value to write:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Badge, Button, Column, Row
from prefab_ui.actions import SetState
from prefab_ui.rx import Rx
drive = Rx("drive")
with Column(gap=3):
with Row(gap=2):
Button("Improbability", variant="outline",
on_click=SetState("drive", "improbability"))
Button("Conventional", variant="outline",
on_click=SetState("drive", "conventional"))
Button("Bistromath", variant="outline",
on_click=SetState("drive", "bistromath"))
Badge(f"Active drive: {drive}")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-3",
"type": "Column",
"children": [
{
"cssClass": "gap-2",
"type": "Row",
"children": [
{
"type": "Button",
"label": "Improbability",
"variant": "outline",
"size": "default",
"disabled": false,
"onClick": {"action": "setState", "key": "drive", "value": "improbability"}
},
{
"type": "Button",
"label": "Conventional",
"variant": "outline",
"size": "default",
"disabled": false,
"onClick": {"action": "setState", "key": "drive", "value": "conventional"}
},
{
"type": "Button",
"label": "Bistromath",
"variant": "outline",
"size": "default",
"disabled": false,
"onClick": {"action": "setState", "key": "drive", "value": "bistromath"}
}
]
},
{"type": "Badge", "label": "Active drive: {{ drive }}", "variant": "default"}
]
}
}
```
### Dot-paths
State keys can contain dots to reach into nested objects. `profile.name` means "the `name` field inside the `profile` object." A purely numeric segment like `0` means an array index, so `todos.0.done` means "the `done` field of the first item in the `todos` array."
The `name` prop works with dot-paths too — type in the inputs below to see the card update:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import (
Card, CardDescription, CardHeader, CardTitle,
Column, Input,
)
from prefab_ui.rx import Rx
profile = Rx("profile")
with Column(gap=3):
with Card():
with CardHeader():
CardTitle(profile.name)
CardDescription(profile.title)
Input(name="profile.name", placeholder="Name")
Input(name="profile.title", placeholder="Title")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-3",
"type": "Column",
"children": [
{
"type": "Card",
"children": [
{
"type": "CardHeader",
"children": [
{"type": "CardTitle", "content": "{{ profile.name }}"},
{"type": "CardDescription", "content": "{{ profile.title }}"}
]
}
]
},
{
"name": "profile.name",
"type": "Input",
"inputType": "text",
"placeholder": "Name",
"disabled": false,
"readOnly": false,
"required": false
},
{
"name": "profile.title",
"type": "Input",
"inputType": "text",
"placeholder": "Title",
"disabled": false,
"readOnly": false,
"required": false
}
]
}
}
```
Integer segments address array items. Inside a [ForEach](/components/foreach) loop, combine this with `{{ $index }}` to target the current row:
```python Array Paths theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Checkbox, Text
from prefab_ui.components.control_flow import ForEach
with ForEach("todos"):
Checkbox(name="todos.{{ $index }}.done")
Text("{{ $item.text }}")
```
`SetState("todos.0.done", True)` would also work for a hardcoded index — but `{{ $index }}` is how you target whichever row the user is interacting with.
If an intermediate path segment is missing or the wrong type (e.g. an integer segment pointing at a non-array), the update is a no-op with a console warning.
## ToggleState
`ToggleState` flips a boolean — `True` becomes `False`, `False` becomes `True`. Pair it with [If](/components/conditional) for show/hide patterns:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Alert, AlertTitle, Button, Column
from prefab_ui.components.control_flow import If
from prefab_ui.actions import ToggleState
from prefab_ui.rx import Rx
showDetails = Rx("showDetails")
with Column(gap=2):
Button("Toggle Details", variant="outline",
on_click=ToggleState("showDetails"))
with If(showDetails):
with Alert():
AlertTitle("Here are the details!")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-2",
"type": "Column",
"children": [
{
"type": "Button",
"label": "Toggle Details",
"variant": "outline",
"size": "default",
"disabled": false,
"onClick": {"action": "toggleState", "key": "showDetails"}
},
{
"type": "Condition",
"cases": [
{
"when": "{{ showDetails }}",
"children": [
{
"type": "Alert",
"variant": "default",
"children": [{"type": "AlertTitle", "content": "Here are the details!"}]
}
]
}
]
}
]
}
}
```
## AppendState and PopState
`AppendState` adds an item to a state array. `PopState` removes one by index. Together with [ForEach](/components/foreach), they let you build dynamic lists entirely client-side.
Type a name and click Add to see it appear in the list. Click × to remove a row.
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import (
Button, Column, ForEach, Input, Muted, Row, Text,
)
from prefab_ui.actions import AppendState, PopState, SetState
from prefab_ui.rx import Rx
new_member = Rx("new_member")
crew = Rx("crew")
with Column(gap=3):
with ForEach("crew"):
with Row(gap=2, align="center"):
Text("{{ $item }}")
Button(
"×", variant="ghost", size="sm",
on_click=PopState("crew", "{{ $index }}"),
)
with Row(gap=2):
Input(name="new_member", placeholder="Crew member name...")
Button("Add", on_click=[
AppendState("crew", new_member),
SetState("new_member", ""),
])
Muted(f"{crew.length()} crew members")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-3",
"type": "Column",
"children": [
{
"let": {"_loop_1": "{{ $item }}", "_loop_1_idx": "{{ $index }}"},
"type": "ForEach",
"key": "crew",
"children": [
{
"cssClass": "gap-2 items-center",
"type": "Row",
"children": [
{"content": "{{ $item }}", "type": "Text"},
{
"type": "Button",
"label": "\u00d7",
"variant": "ghost",
"size": "sm",
"disabled": false,
"onClick": {"action": "popState", "key": "crew", "index": "{{ $index }}"}
}
]
}
]
},
{
"cssClass": "gap-2",
"type": "Row",
"children": [
{
"name": "new_member",
"type": "Input",
"inputType": "text",
"placeholder": "Crew member name...",
"disabled": false,
"readOnly": false,
"required": false
},
{
"type": "Button",
"label": "Add",
"variant": "default",
"size": "default",
"disabled": false,
"onClick": [
{"action": "appendState", "key": "crew", "value": "{{ new_member }}"},
{"action": "setState", "key": "new_member", "value": ""}
]
}
]
},
{"content": "{{ crew | length }} crew members", "type": "Muted"}
]
}
}
```
The "Add" button chains two actions: `AppendState` pushes the input value onto the array, then `SetState` clears the input. Each × button uses `PopState` with `{{ $index }}` — a variable provided by `ForEach` that gives the current row's position.
`AppendState` can also insert at a specific position with `index=0` to prepend or negative indices to count from the end. If the key doesn't exist yet, it creates a new array automatically.
## Valid State Keys
State keys must be identifiers: letters, numbers, and underscores, starting with a letter or underscore (`volume`, `_count`, `item_2`). No hyphens (they conflict with expressions) and no periods (the dot is the path separator). These rules are validated in Python when you create the action.
## API Reference
State key, dot-path, `Rx` reference, or a stateful component (Slider, Input, Pages, etc.). When a component is passed, its state key is extracted automatically.
Value to assign. Defaults to `EVENT` — the value from the triggering interaction (slider position, input text, checkbox state, etc.).
State key, dot-path, `Rx` reference, or a stateful component.
State key, dot-path, `Rx` reference, or a stateful component.
Value to append.
Insert position. `None` appends to end. Supports negative indices and template strings like `"{{ $index }}"`.
State key, dot-path, `Rx` reference, or a stateful component.
Index to remove. Supports negative indices and template strings like `"{{ $index }}"`.
## Protocol Reference
```json SetState theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"action": "setState",
"key": "string (required)",
"value": "any (required)"
}
```
```json ToggleState theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"action": "toggleState",
"key": "string (required)"
}
```
```json AppendState theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"action": "appendState",
"key": "string (required)",
"value": "any (required)",
"index?": "number | string"
}
```
```json PopState theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"action": "popState",
"key": "string (required)",
"index": "number | string (required)"
}
```
For the complete protocol schema, see [SetState](/protocol/set-state), [ToggleState](/protocol/toggle-state), [AppendState](/protocol/append-state), [PopState](/protocol/pop-state).