---
title: Pages
description: Multi-page layout that swaps content via state.
icon: files
---

import { ComponentPreview } from '/snippets/component-preview.mdx'

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

<ComponentPreview json={{"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","type":"Pages","defaultValue":"earth","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"}}} playground=" ">
<CodeGroup>
```python Python icon="python"
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", default_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"
{
  "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",
        "type": "Pages",
        "defaultValue": "earth",
        "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"}
}
```
</CodeGroup>
</ComponentPreview>

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.rx` to `SetState` instead of hardcoding the state key:

<ComponentPreview json={{"view":{"cssClass":"gap-4","type":"Column","children":[{"name":"pages_1","type":"Pages","defaultValue":"setup","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"}}} playground=" ">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Button, Column, Page, Pages, Row, Text
from prefab_ui.actions import SetState

with Column(gap=4):
    with Pages(default_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.rx, "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.rx, "setup"))
                    Button("Next", on_click=SetState(pages.rx, "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"
{
  "view": {
    "cssClass": "gap-4",
    "type": "Column",
    "children": [
      {
        "name": "pages_1",
        "type": "Pages",
        "defaultValue": "setup",
        "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"}
}
```
</CodeGroup>
</ComponentPreview>

## 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:

<ComponentPreview json={{"view":{"cssClass":"justify-around w-full","type":"Row","children":[{"cssClass":"gap-4 w-auto","type":"Column","children":[{"name":"pages_2","type":"Pages","defaultValue":"profile","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,"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"}}} playground=" ">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import (
    Column, Heading, Page, Pages, Row, Select, SelectOption, Text,
)
from prefab_ui.actions import SetState

with Row(justify="around", css_class="w-full"):
    with Column(gap=4, css_class="w-auto"):
        with Pages(default_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.rx, "{{ $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"
{
  "view": {
    "cssClass": "justify-around w-full",
    "type": "Row",
    "children": [
      {
        "cssClass": "gap-4 w-auto",
        "type": "Column",
        "children": [
          {
            "name": "pages_2",
            "type": "Pages",
            "defaultValue": "profile",
            "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,
            "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"}
}
```
</CodeGroup>
</ComponentPreview>

The `SetState(pages.rx, "{{ $event }}")` writes the Select's chosen value into the pages' state key, switching the visible page. `{{ $event }}` is a special variable containing the value from the triggering component.

## API Reference

<Card icon="code" title="Pages Parameters">
<ParamField body="default_value" type="str | None" default="None">
  Value of the initially active page.
</ParamField>

<ParamField body="name" type="str | None" default="None">
  State key for tracking the active page. Other components can write to this key with `SetState`.
</ParamField>

<ParamField body="css_class" type="str | None" default="None">
  Additional Tailwind CSS classes.
</ParamField>
</Card>

<Card icon="code" title="Page Parameters">
<ParamField body="title" type="str" required>
  Page identifier. Can be passed as a positional argument.
</ParamField>

<ParamField body="value" type="str | None" default="None">
  Unique value for this page. Defaults to the title.
</ParamField>
</Card>

## Protocol Reference

```json Pages
{
  "type": "Pages",
  "children?": "[Component]",
  "let?": "object",
  "name?": "string",
  "defaultValue?": "string",
  "cssClass?": "string"
}
```

```json Page
{
  "type": "Page",
  "children?": "[Component]",
  "let?": "object",
  "title": "string (required)",
  "value?": "string",
  "cssClass?": "string"
}
```

For the complete protocol schema, see [Pages](/protocol/pages), [Page](/protocol/page).
