---
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"}}]},{"type":"Pages","defaultValue":"earth","name":"entry","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."}]}]}]}]}]}}}>
<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"
            }
          }
        ]
      },
      {
        "type": "Pages",
        "defaultValue": "earth",
        "name": "entry",
        "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."
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}
```
</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:

<ComponentPreview json={{"view":{"cssClass":"gap-4","type":"Column","children":[{"type":"Pages","defaultValue":"setup","name":"step","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":"step","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":"step","value":"setup"}},{"type":"Button","label":"Next","variant":"default","size":"default","disabled":false,"onClick":{"action":"setState","key":"step","value":"complete"}}]}]}]},{"type":"Page","title":"Complete","value":"complete","children":[{"content":"All done!","type":"Text"}]}]}]}}}>
<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(name="step", default_value="setup"):
        with Page("Setup", value="setup"):
            with Column(gap=4):
                Text("Configure your settings.")
                with Row():
                    Button("Next", on_click=SetState("step", "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("step", "setup"))
                    Button("Next", on_click=SetState("step", "complete"))
        with Page("Complete", value="complete"):
            Text("All done!")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4",
    "type": "Column",
    "children": [
      {
        "type": "Pages",
        "defaultValue": "setup",
        "name": "step",
        "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": "step",
                          "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": "step",
                          "value": "setup"
                        }
                      },
                      {
                        "type": "Button",
                        "label": "Next",
                        "variant": "default",
                        "size": "default",
                        "disabled": false,
                        "onClick": {
                          "action": "setState",
                          "key": "step",
                          "value": "complete"
                        }
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "type": "Page",
            "title": "Complete",
            "value": "complete",
            "children": [
              {
                "content": "All done!",
                "type": "Text"
              }
            ]
          }
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## 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",
  "defaultValue?": "string",
  "name?": "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).
