fastmcp/docs/apps/components.mdx

---
title: Component Reference
sidebarTitle: Components
description: Quick reference for the most-used Prefab components.
icon: shapes
tag: NEW
---

import { VersionBadge } from '/snippets/version-badge.mdx'

<VersionBadge version="3.1.0" />

This page is a scannable reference for the Prefab components you'll use most often in MCP Apps. Each entry shows the component, what it does, a minimal code example, and the props that matter.

For the full component library — every prop, variant, and advanced pattern — see the [Prefab component reference](https://prefab.prefect.io/docs/components).

<Note>
All components below are imported from `prefab_ui.components` unless otherwise noted. Charts must be imported from `prefab_ui.components.charts`.
</Note>

## Layout

Layout components control how children are arranged. They all use Python's `with` statement to collect their children.

### Column

Stacks children vertically. The most common top-level container for an app view.

```python
from prefab_ui.components import Column, Text

with Column(gap=4, css_class="p-6") as view:
    Text("First")
    Text("Second")
```

| Prop | Type | Description |
|------|------|-------------|
| `gap` | `int` | Space between children (Tailwind units) |
| `align` | `str` | Cross-axis alignment: `"start"`, `"center"`, `"end"`, `"stretch"` |
| `justify` | `str` | Main-axis alignment: `"start"`, `"center"`, `"end"`, `"between"` |
| `css_class` | `str` | Tailwind CSS classes |

### Row

Arranges children horizontally.

```python
from prefab_ui.components import Row, Badge, Text

with Row(gap=2, align="center"):
    Text("Status")
    Badge("Online", variant="success")
```

| Prop | Type | Description |
|------|------|-------------|
| `gap` | `int` | Space between children |
| `align` | `str` | Cross-axis alignment |
| `justify` | `str` | Main-axis alignment |
| `wrap` | `bool` | Wrap children to next line |

### Grid

Lays out children in a CSS grid with a fixed number of columns.

```python
from prefab_ui.components import Grid, Card, CardContent, Text

with Grid(columns=3, gap=4):
    for label in ["API", "Cache", "DB"]:
        with Card():
            with CardContent():
                Text(label)
```

| Prop | Type | Description |
|------|------|-------------|
| `columns` | `int` | Number of grid columns |
| `gap` | `int` | Space between cells |

### Card / CardContent

A bordered container with padding. `Card` provides the outer border and shadow; `CardContent` adds standard inner padding. Cards are commonly used inside grids for dashboard-style layouts.

```python
from prefab_ui.components import Card, CardContent, Text, Badge

with Card():
    with CardContent():
        Text("API Gateway")
        Badge("healthy", variant="success")
```

| Prop | Type | Description |
|------|------|-------------|
| `css_class` | `str` | Additional Tailwind classes |

### Separator

Renders a horizontal rule between sections. Takes no required props.

```python
from prefab_ui.components import Column, Heading, Separator, Text

with Column(gap=4):
    Heading("Section A")
    Separator()
    Text("Content below the line")
```

## Typography

### Heading

Renders a heading element. Defaults to `level=2` (an `<h2>`).

```python
from prefab_ui.components import Heading

Heading("Dashboard")
Heading("Subsection", level=3)
```

| Prop | Type | Description |
|------|------|-------------|
| `level` | `int` | Heading level: `1`-`4` |

### Text

General-purpose text element. Accepts reactive expressions (`Rx`) as content so the text can update with state changes.

```python
from prefab_ui.components import Text

Text("Hello, world")
Text("Styled text", css_class="font-medium text-blue-500")
```

| Prop | Type | Description |
|------|------|-------------|
| `css_class` | `str` | Tailwind CSS classes |

### Muted

Renders text in a subdued color. Useful for secondary information like timestamps, metadata, or helper text.

```python
from prefab_ui.components import Muted

Muted("Last updated 5 minutes ago")
```

### Badge

A small label for status indicators, tags, or categories. Supports color variants to convey meaning at a glance.

```python
from prefab_ui.components import Badge

Badge("Active", variant="success")
Badge("Pending", variant="warning")
Badge("Failed", variant="destructive")
```

| Prop | Type | Description |
|------|------|-------------|
| `variant` | `str` | `"default"`, `"success"`, `"warning"`, `"destructive"`, `"outline"` |

## Data

### DataTable

A fully interactive table with client-side sorting, searching, and pagination. You define columns and pass row data as a list of dicts.

```python
from prefab_ui.components import DataTable, DataTableColumn

DataTable(
    columns=[
        DataTableColumn(key="name", header="Name", sortable=True),
        DataTableColumn(key="role", header="Role"),
    ],
    rows=[
        {"name": "Alice", "role": "Engineer"},
        {"name": "Bob", "role": "Designer"},
    ],
    search=True,
    paginated=True,
    page_size=15,
)
```

| Prop | Type | Description |
|------|------|-------------|
| `columns` | `list[DataTableColumn]` | Column definitions |
| `rows` | `list[dict]` | Row data |
| `search` | `bool` | Enable full-text search |
| `paginated` | `bool` | Enable pagination |
| `page_size` | `int` | Rows per page (default `10`) |

`DataTableColumn` takes `key` (the dict key), `header` (display name), and `sortable` (enable sorting on that column).

### BarChart

Renders vertical or horizontal bar charts. Each `ChartSeries` maps a key from your data to a colored bar group. Multiple series produce grouped (or stacked) bars.

```python
from prefab_ui.components.charts import BarChart, ChartSeries

BarChart(
    data=[
        {"month": "Jan", "revenue": 4200},
        {"month": "Feb", "revenue": 5100},
    ],
    series=[ChartSeries(data_key="revenue", label="Revenue")],
    x_axis="month",
    show_legend=True,
)
```

| Prop | Type | Description |
|------|------|-------------|
| `data` | `list[dict]` | Chart data |
| `series` | `list[ChartSeries]` | Data series to plot |
| `x_axis` | `str` | Key for the x-axis labels |
| `stacked` | `bool` | Stack bars instead of grouping |
| `horizontal` | `bool` | Flip axes for horizontal bars |
| `show_legend` | `bool` | Display the legend |
| `height` | `int` | Chart height in pixels |

### PieChart

Displays proportional data as slices. Set `inner_radius` for a donut chart. Unlike bar/line charts, `PieChart` uses `data_key` for the numeric value and `name_key` for the label — it doesn't use `ChartSeries`.

```python
from prefab_ui.components.charts import PieChart

PieChart(
    data=[
        {"category": "Bug", "count": 23},
        {"category": "Feature", "count": 15},
    ],
    data_key="count",
    name_key="category",
    inner_radius=60,
    show_legend=True,
)
```

| Prop | Type | Description |
|------|------|-------------|
| `data` | `list[dict]` | Chart data |
| `data_key` | `str` | Key for the numeric value |
| `name_key` | `str` | Key for the label |
| `inner_radius` | `int` | Inner radius for donut charts (0 = full pie) |
| `show_legend` | `bool` | Display the legend |

### LineChart

Plots data points connected by lines. Shares the same API as `BarChart` — use `series`, `x_axis`, and optionally `curve` to control interpolation.

```python
from prefab_ui.components.charts import LineChart, ChartSeries

LineChart(
    data=[
        {"day": "Mon", "requests": 120},
        {"day": "Tue", "requests": 185},
    ],
    series=[ChartSeries(data_key="requests", label="Requests")],
    x_axis="day",
    curve="smooth",
    show_dots=True,
)
```

| Prop | Type | Description |
|------|------|-------------|
| `data` | `list[dict]` | Chart data |
| `series` | `list[ChartSeries]` | Data series to plot |
| `x_axis` | `str` | Key for x-axis labels |
| `curve` | `str` | `"linear"` or `"smooth"` |
| `show_dots` | `bool` | Show data point markers |
| `height` | `int` | Chart height in pixels |

## Forms

Form components collect user input. Each has a `name` prop that determines the key in the submitted data. When used inside a `Form`, their values are gathered automatically on submit.

### Input

A single-line text field. Set `input_type` to `"email"`, `"password"`, `"number"`, etc. for browser-native validation.

```python
from prefab_ui.components import Input

Input(name="email", label="Email", input_type="email", required=True)
Input(name="search", placeholder="Search...")
```

| Prop | Type | Description |
|------|------|-------------|
| `name` | `str` | State/form key |
| `label` | `str` | Label text |
| `placeholder` | `str` | Placeholder text |
| `input_type` | `str` | HTML input type |
| `required` | `bool` | Mark as required |
| `disabled` | `bool` | Disable input |

### Select

A dropdown for choosing from a list of options. Pass a flat list of strings, or structured `SelectOption` objects for custom labels.

```python
from prefab_ui.components import Select, SelectOption

with Select(name="priority", label="Priority"):
    SelectOption("Low", value="low")
    SelectOption("Medium", value="medium")
    SelectOption("High", value="high")
```

Options are defined as `SelectOption` children, not as a prop.

| Prop | Type | Description |
|------|------|-------------|
| `name` | `str` | State/form key |
| `label` | `str` | Label text |
| `placeholder` | `str` | Placeholder text |

### Textarea

A multi-line text area. Works the same as `Input` but renders as a resizable text box.

```python
from prefab_ui.components import Textarea

Textarea(name="notes", label="Notes", placeholder="Add details...")
```

| Prop | Type | Description |
|------|------|-------------|
| `name` | `str` | State/form key |
| `label` | `str` | Label text |
| `placeholder` | `str` | Placeholder text |
| `rows` | `int` | Visible height in rows |

### Checkbox

A boolean toggle rendered as a checkbox. Binds to state as `True`/`False`.

```python
from prefab_ui.components import Checkbox

Checkbox(name="agree", label="I agree to the terms")
```

| Prop | Type | Description |
|------|------|-------------|
| `name` | `str` | State/form key |
| `label` | `str` | Label text |

### Switch

A toggle switch. Functionally identical to `Checkbox` but rendered as a sliding toggle, better suited for settings and feature flags.

```python
from prefab_ui.components import Switch

Switch(name="dark_mode", label="Dark Mode")
```

| Prop | Type | Description |
|------|------|-------------|
| `name` | `str` | State/form key |
| `label` | `str` | Label text |

### Slider

A range input for numeric values. The user drags a handle between `min` and `max`.

```python
from prefab_ui.components import Slider

Slider(name="volume", label="Volume", min=0, max=100, step=1)
```

| Prop | Type | Description |
|------|------|-------------|
| `name` | `str` | State/form key |
| `label` | `str` | Label text |
| `min` | `float` | Minimum value |
| `max` | `float` | Maximum value |
| `step` | `float` | Step increment |

### Form

Wraps input components and gathers their values on submit. Attach a `CallTool` action to `on_submit` to send the data to the server. Every named input inside the form becomes a key in the arguments dict.

```python
from prefab_ui.components import Form, Input, Button
from prefab_ui.actions.mcp import CallTool

with Form(on_submit=CallTool("save_contact")):
    Input(name="name", label="Name", required=True)
    Input(name="email", label="Email", required=True)
    Button("Save")
```

| Prop | Type | Description |
|------|------|-------------|
| `on_submit` | `Action` | Action to run when the form is submitted |

### Button

A clickable button. Inside a `Form`, a button triggers form submission by default. Outside a form, attach actions to `on_click`.

```python
from prefab_ui.components import Button
from prefab_ui.actions import SetState

Button("Reset", on_click=SetState("count", 0))
```

| Prop | Type | Description |
|------|------|-------------|
| `variant` | `str` | `"default"`, `"outline"`, `"ghost"`, `"destructive"` |
| `on_click` | `Action` | Action to run on click |
| `disabled` | `bool` | Disable the button |

## Containers

### Tabs / Tab

Organizes content into switchable panels. Each `Tab` becomes a panel with a label in the tab bar. Switching tabs is instant — all panels are rendered, only one is visible.

```python
from prefab_ui.components import Tabs, Tab, Text

with Tabs():
    with Tab("Overview"):
        Text("Overview content here")
    with Tab("Details"):
        Text("Detail content here")
```

| Prop (Tabs) | Type | Description |
|-------------|------|-------------|
| `value` | `str` | Label of the initially active tab |

### Accordion / AccordionItem

Collapsible sections. Each `AccordionItem` has a title that toggles its content open and closed. By default, only one item is open at a time.

```python
from prefab_ui.components import Accordion, AccordionItem, Text

with Accordion(multiple=True):
    with AccordionItem("Section A"):
        Text("Content for section A")
    with AccordionItem("Section B"):
        Text("Content for section B")
```

| Prop (Accordion) | Type | Description |
|------------------|------|-------------|
| `multiple` | `bool` | Allow multiple items open simultaneously |

### Dialog

A modal overlay that appears above the page content. Pair it with a trigger (like a `Button`) to open and close it.

```python
from prefab_ui.components import Dialog, Column, Heading, Text

with Dialog(title="Confirm Delete"):
    with Column(gap=2):
        Text("Are you sure you want to delete this item?")
```

| Prop | Type | Description |
|------|------|-------------|
| `title` | `str` | Dialog title in the header |
| `description` | `str` | Subtitle below the title |

### Pages / Page

Multi-page navigation within a single app. `Pages` renders one `Page` at a time, controlled by state. Useful for multi-step workflows and wizards.

```python
from prefab_ui.app import set_initial_state
from prefab_ui.components import Pages, Page, Text, Button
from prefab_ui.actions import SetState

state = set_initial_state(page="welcome")

with Pages(active_page=state.page):
    with Page("welcome"):
        Text("Welcome!")
        Button("Next", on_click=SetState("page", "setup"))
    with Page("setup"):
        Text("Configure your settings")
```

| Prop (Pages) | Type | Description |
|-------------|------|-------------|
| `active_page` | `str \| Rx` | The label of the currently visible page |

## Control Flow

Control flow components conditionally show or iterate over children based on reactive state. They evaluate in the browser, so changes are instant.

### If / Elif / Else

Conditionally render content based on state values. `If` evaluates an `Rx` expression; `Elif` and `Else` follow the same pattern as Python's branching.

```python
from prefab_ui.app import set_initial_state
from prefab_ui.components import If, Elif, Else, Text, Select

state = set_initial_state(role="viewer")

Select(name="role", options=["viewer", "editor", "admin"])
with If(state.role == "admin"):
    Text("Full access")
with Elif(state.role == "editor"):
    Text("Edit access")
with Else():
    Text("Read-only access")
```

### ForEach

Iterates over a state array and renders children for each item. The loop variable is an `Rx` proxy scoped to the current item, so `item.name` resolves at render time.

```python
from prefab_ui.components import ForEach, Row, Text, Badge

with ForEach("users") as user:
    with Row(gap=2):
        Text(user.name)
        Badge(user.role)
```

| Prop | Type | Description |
|------|------|-------------|
| first arg | `str` | The state key containing the array |

## Feedback

### Alert

A callout box for important messages. Supports variants to signal severity.

```python
from prefab_ui.components import Alert

Alert(title="Deployment complete", variant="success")
Alert(
    title="Rate limit approaching",
    description="Current usage is at 85% of your plan limit.",
    variant="warning",
)
```

| Prop | Type | Description |
|------|------|-------------|
| `title` | `str` | Alert heading |
| `description` | `str` | Body text |
| `variant` | `str` | `"default"`, `"success"`, `"warning"`, `"destructive"` |

### Progress

A horizontal progress bar. Pass a `value` between 0 and 100. Supports reactive values so the bar updates as state changes.

```python
from prefab_ui.components import Progress

Progress(value=75)
```

| Prop | Type | Description |
|------|------|-------------|
| `value` | `int \| Rx` | Progress percentage (0-100) |

### Loader

A spinning indicator for loading states. Takes no required props — just drop it in and it spins.

```python
from prefab_ui.components import Loader

Loader()
```

---

For the complete API — including additional components like `Metric`, `Calendar`, `Markdown`, `Embed`, and advanced chart types — see the [Prefab component reference](https://prefab.prefect.io/docs/components).