> ## Documentation Index
> Fetch the complete documentation index at: https://prefab.prefect.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Pages
> Multi-page layout that swaps content via state.
export const ComponentPreview = ({json, height, resizable, bare, hideJson, playground, children}) => {
const hostRef = React.useRef(null);
const handleRef = React.useRef(null);
const cardRef = React.useRef(null);
const containerRef = React.useRef(null);
const [previewWidth, setPreviewWidth] = React.useState(null);
const [isDragging, setIsDragging] = React.useState(false);
const [playgroundHref, setPlaygroundHref] = React.useState(null);
React.useEffect(function () {
if (!playground) return;
var isLocal = location.hostname === "localhost" || location.hostname === "127.0.0.1";
var path = isLocal ? "/playground" : "/docs/playground";
var url = new URL(path, window.location.href);
url.hash = "code=" + playground;
setPlaygroundHref(url.href);
}, [playground]);
var jsonStr = typeof json === "string" ? json : JSON.stringify(json, null, 2);
React.useEffect(function () {
if (cardRef.current) {
var card = cardRef.current.closest(".group");
if (card) card.classList.remove("group");
}
var host = hostRef.current;
if (!host || !json) return;
function mount() {
if (!window.__prefab || !host) return;
var dark = document.documentElement.classList.contains("dark");
handleRef.current = window.__prefab.mountPreview(host, jsonStr, {
dark: dark
});
if (bare && host.shadowRoot) {
var m = host.shadowRoot.querySelector("[data-prefab-mount]");
if (m) m.style.background = "transparent";
}
}
if (window.__prefab) {
mount();
} else {
if (!window.__prefabLoading) {
if (!window.__prefabReady) {
var s = document.createElement("script");
s.src = "/renderer.js";
document.head.appendChild(s);
}
window.__prefabLoading = new Promise(function (resolve) {
function check() {
if (window.__prefabReady) {
window.__prefabReady.then(resolve);
} else {
setTimeout(check, 10);
}
}
check();
});
}
window.__prefabLoading.then(mount);
}
var observer = new MutationObserver(function () {
var dark = document.documentElement.classList.contains("dark");
if (handleRef.current) handleRef.current.setDark(dark);
});
observer.observe(document.documentElement, {
attributes: true,
attributeFilter: ["class"]
});
return function () {
observer.disconnect();
if (handleRef.current) {
handleRef.current.unmount();
handleRef.current = null;
}
};
}, [json]);
function startResize(e) {
e.preventDefault();
var startX = e.clientX;
var startW = hostRef.current ? hostRef.current.offsetWidth : 0;
var maxW = containerRef.current ? containerRef.current.offsetWidth - 10 : startW;
setIsDragging(true);
function onMove(ev) {
var w = Math.max(260, Math.min(startW + (ev.clientX - startX), maxW));
setPreviewWidth(w);
}
function onUp() {
document.removeEventListener("mousemove", onMove);
document.removeEventListener("mouseup", onUp);
setIsDragging(false);
}
document.addEventListener("mousemove", onMove);
document.addEventListener("mouseup", onUp);
}
if (bare) {
return ;
}
if (resizable) {
return
{previewWidth &&
{previewWidth}px
}
{playgroundHref && }
{children}
;
}
return
{playgroundHref && }
{children}
;
};
Pages provide a multi-page layout where only the active page renders. Navigate between pages by setting client state — there's no tab bar, so you control the navigation UI yourself with buttons, links, or any other component.
## Basic Usage
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import (
Button,
Card,
CardDescription,
CardHeader,
CardTitle,
Column,
Page,
Pages,
Row,
)
from prefab_ui.actions import SetState
with Column(gap=4):
with Row(gap=2):
Button("Earth", on_click=SetState("entry", "earth"))
Button("Magrathea", variant="outline", on_click=SetState("entry", "magrathea"))
Button("Milliways", variant="outline", on_click=SetState("entry", "milliways"))
with Pages(name="entry", value="earth"):
with Page("Earth", value="earth"):
with Card():
with CardHeader():
CardTitle("Earth")
CardDescription("Mostly harmless.")
with Page("Magrathea", value="magrathea"):
with Card():
with CardHeader():
CardTitle("Magrathea")
CardDescription(
"Ancient planet-building civilization. "
"Custom-built luxury planets for the ultra-rich."
)
with Page("Milliways", value="milliways"):
with Card():
with CardHeader():
CardTitle("Milliways")
CardDescription(
"The Restaurant at the End of the Universe. "
"Reservations recommended."
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-4",
"type": "Column",
"children": [
{
"cssClass": "gap-2",
"type": "Row",
"children": [
{
"type": "Button",
"label": "Earth",
"variant": "default",
"size": "default",
"disabled": false,
"onClick": {"action": "setState", "key": "entry", "value": "earth"}
},
{
"type": "Button",
"label": "Magrathea",
"variant": "outline",
"size": "default",
"disabled": false,
"onClick": {"action": "setState", "key": "entry", "value": "magrathea"}
},
{
"type": "Button",
"label": "Milliways",
"variant": "outline",
"size": "default",
"disabled": false,
"onClick": {"action": "setState", "key": "entry", "value": "milliways"}
}
]
},
{
"name": "entry",
"value": "earth",
"type": "Pages",
"children": [
{
"type": "Page",
"title": "Earth",
"value": "earth",
"children": [
{
"type": "Card",
"children": [
{
"type": "CardHeader",
"children": [
{"type": "CardTitle", "content": "Earth"},
{"type": "CardDescription", "content": "Mostly harmless."}
]
}
]
}
]
},
{
"type": "Page",
"title": "Magrathea",
"value": "magrathea",
"children": [
{
"type": "Card",
"children": [
{
"type": "CardHeader",
"children": [
{"type": "CardTitle", "content": "Magrathea"},
{
"type": "CardDescription",
"content": "Ancient planet-building civilization. Custom-built luxury planets for the ultra-rich."
}
]
}
]
}
]
},
{
"type": "Page",
"title": "Milliways",
"value": "milliways",
"children": [
{
"type": "Card",
"children": [
{
"type": "CardHeader",
"children": [
{"type": "CardTitle", "content": "Milliways"},
{
"type": "CardDescription",
"content": "The Restaurant at the End of the Universe. Reservations recommended."
}
]
}
]
}
]
}
]
}
]
},
"state": {"entry": "earth"}
}
```
The `name` prop connects the Pages component to client state. When the `entry` key changes (via `SetState`), the corresponding page renders. This makes Pages ideal for wizard flows, multi-step forms, or any layout where you want to swap entire sections without a server round-trip.
## Step-by-Step Navigation
Pages pair naturally with `SetState` to build wizard flows. Each page's button advances to the next step. Use `as pages` to capture the reference, then pass `pages` directly to `SetState` instead of hardcoding the state key:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Button, Column, Page, Pages, Row, Text
from prefab_ui.actions import SetState
with Column(gap=4):
with Pages(value="setup") as pages:
with Page("Setup", value="setup"):
with Column(gap=4):
Text("Configure your settings.")
with Row():
Button("Next", on_click=SetState(pages, "review"))
with Page("Review", value="review"):
with Column(gap=4):
Text("Review your choices.")
with Row(gap=2):
Button("Back", variant="outline", on_click=SetState(pages, "setup"))
Button("Next", on_click=SetState(pages, "complete"))
with Page("Complete", value="complete"):
Text("All done!")
Text(f"Current step: {pages.rx}", css_class="text-muted-foreground text-sm")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-4",
"type": "Column",
"children": [
{
"name": "pages_1",
"value": "setup",
"type": "Pages",
"children": [
{
"type": "Page",
"title": "Setup",
"value": "setup",
"children": [
{
"cssClass": "gap-4",
"type": "Column",
"children": [
{"content": "Configure your settings.", "type": "Text"},
{
"type": "Row",
"children": [
{
"type": "Button",
"label": "Next",
"variant": "default",
"size": "default",
"disabled": false,
"onClick": {"action": "setState", "key": "pages_1", "value": "review"}
}
]
}
]
}
]
},
{
"type": "Page",
"title": "Review",
"value": "review",
"children": [
{
"cssClass": "gap-4",
"type": "Column",
"children": [
{"content": "Review your choices.", "type": "Text"},
{
"cssClass": "gap-2",
"type": "Row",
"children": [
{
"type": "Button",
"label": "Back",
"variant": "outline",
"size": "default",
"disabled": false,
"onClick": {"action": "setState", "key": "pages_1", "value": "setup"}
},
{
"type": "Button",
"label": "Next",
"variant": "default",
"size": "default",
"disabled": false,
"onClick": {"action": "setState", "key": "pages_1", "value": "complete"}
}
]
}
]
}
]
},
{
"type": "Page",
"title": "Complete",
"value": "complete",
"children": [{"content": "All done!", "type": "Text"}]
}
]
},
{
"cssClass": "text-muted-foreground text-sm",
"content": "Current step: {{ pages_1 }}",
"type": "Text"
}
]
},
"state": {"pages_1": "setup"}
}
```
## Reading the Value
Use `.rx` to get a reactive reference to the active page's value string. Since Pages has no built-in navigation, you provide your own — here a `Select` drives which page is shown:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import (
Column, Heading, Page, Pages, Row, Select, SelectOption, Text,
)
from prefab_ui.actions import SetState
from prefab_ui.rx import EVENT
with Row(justify="around", css_class="w-full"):
with Column(gap=4, css_class="w-auto"):
with Pages(value="profile") as pages:
with Page("Profile", value="profile"):
Heading("Profile", level=4)
Text("Update your display name and avatar.")
with Page("Notifications", value="notifications"):
Heading("Notifications", level=4)
Text("Choose what triggers an alert.")
with Page("Security", value="security"):
Heading("Security", level=4)
Text("Two-factor authentication and sessions.")
with Column(gap=4, css_class="w-auto"):
with Select(
placeholder="Jump to...",
on_change=SetState(pages, EVENT),
):
SelectOption("Profile", value="profile")
SelectOption("Notifications", value="notifications")
SelectOption("Security", value="security")
Text(
f"Section: {pages.rx}",
css_class="text-muted-foreground text-sm",
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "justify-around w-full",
"type": "Row",
"children": [
{
"cssClass": "gap-4 w-auto",
"type": "Column",
"children": [
{
"name": "pages_2",
"value": "profile",
"type": "Pages",
"children": [
{
"type": "Page",
"title": "Profile",
"value": "profile",
"children": [
{"content": "Profile", "type": "Heading", "level": 4},
{"content": "Update your display name and avatar.", "type": "Text"}
]
},
{
"type": "Page",
"title": "Notifications",
"value": "notifications",
"children": [
{"content": "Notifications", "type": "Heading", "level": 4},
{"content": "Choose what triggers an alert.", "type": "Text"}
]
},
{
"type": "Page",
"title": "Security",
"value": "security",
"children": [
{"content": "Security", "type": "Heading", "level": 4},
{"content": "Two-factor authentication and sessions.", "type": "Text"}
]
}
]
}
]
},
{
"cssClass": "gap-4 w-auto",
"type": "Column",
"children": [
{
"name": "select_1",
"type": "Select",
"placeholder": "Jump to...",
"size": "default",
"disabled": false,
"required": false,
"invalid": false,
"onChange": {"action": "setState", "key": "pages_2", "value": "{{ $event }}"},
"children": [
{
"type": "SelectOption",
"value": "profile",
"label": "Profile",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "notifications",
"label": "Notifications",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "security",
"label": "Security",
"selected": false,
"disabled": false
}
]
},
{
"cssClass": "text-muted-foreground text-sm",
"content": "Section: {{ pages_2 }}",
"type": "Text"
}
]
}
]
},
"state": {"pages_2": "profile"}
}
```
`SetState` accepts a stateful component directly — it extracts the state key automatically. So `SetState(pages, EVENT)` writes the Select's chosen value into the pages' state key, switching the visible page. `EVENT` is a reactive reference that resolves to the value from the triggering component.
## API Reference
Value of the initially active page.
State key for tracking the active page. Other components can write to this key with `SetState`.
Additional Tailwind CSS classes.
Page identifier. Can be passed as a positional argument.
Unique value for this page. Defaults to the title.
## Protocol Reference
```json Pages theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "Pages",
"id?": "string",
"onMount?": "any",
"children?": "[Component]",
"let?": "object",
"name?": "string",
"value?": "string",
"cssClass?": "string"
}
```
```json Page theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "Page",
"id?": "string",
"onMount?": "any",
"children?": "[Component]",
"let?": "object",
"title": "string (required)",
"value?": "string",
"cssClass?": "string"
}
```
For the complete protocol schema, see [Pages](/protocol/pages), [Page](/protocol/page).