> ## 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.
# Select
> Dropdown select for choosing from a list of options.
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}
;
};
Select dropdowns let users pick one option from a collapsible list. The selected option's `value` string is stored in client state, accessible via `.rx`.
## Basic Usage
A `Select` is a container — use the `with` block to add `SelectOption` children. Each option needs a `value` (what gets stored) and a `label` (what the user sees):
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Select, SelectOption
with Select(placeholder="Choose size...", css_class="w-fit"):
SelectOption(value="sm", label="Small")
SelectOption(value="md", label="Medium")
SelectOption(value="lg", label="Large")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "w-fit",
"name": "select_2",
"type": "Select",
"placeholder": "Choose size...",
"size": "default",
"disabled": false,
"required": false,
"invalid": false,
"children": [
{
"type": "SelectOption",
"value": "sm",
"label": "Small",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "md",
"label": "Medium",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "lg",
"label": "Large",
"selected": false,
"disabled": false
}
]
}
}
```
## Pre-selected Option
Mark an option as `selected=True` to have it chosen when the component first renders:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Select, SelectOption
with Select(placeholder="Select country", css_class="w-fit mx-auto"):
SelectOption(value="us", label="United States")
SelectOption(value="uk", label="United Kingdom", selected=True)
SelectOption(value="ca", label="Canada")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "w-fit mx-auto",
"name": "select_3",
"type": "Select",
"placeholder": "Select country",
"size": "default",
"disabled": false,
"required": false,
"invalid": false,
"children": [
{
"type": "SelectOption",
"value": "us",
"label": "United States",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "uk",
"label": "United Kingdom",
"selected": true,
"disabled": false
},
{
"type": "SelectOption",
"value": "ca",
"label": "Canada",
"selected": false,
"disabled": false
}
]
}
}
```
## Sizes
Selects come in two sizes. The `"sm"` variant is useful when space is tight or when embedding a select alongside other compact controls:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Column, Select, SelectOption
with Column(gap=4, css_class="w-fit min-w-[200px] mx-auto"):
with Select(placeholder="Default size"):
SelectOption(value="1", label="Option 1")
SelectOption(value="2", label="Option 2")
with Select(placeholder="Small size", size="sm"):
SelectOption(value="1", label="Option 1")
SelectOption(value="2", label="Option 2")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-4 w-fit min-w-[200px] mx-auto",
"type": "Column",
"children": [
{
"name": "select_4",
"type": "Select",
"placeholder": "Default size",
"size": "default",
"disabled": false,
"required": false,
"invalid": false,
"children": [
{
"type": "SelectOption",
"value": "1",
"label": "Option 1",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "2",
"label": "Option 2",
"selected": false,
"disabled": false
}
]
},
{
"name": "select_5",
"type": "Select",
"placeholder": "Small size",
"size": "sm",
"disabled": false,
"required": false,
"invalid": false,
"children": [
{
"type": "SelectOption",
"value": "1",
"label": "Option 1",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "2",
"label": "Option 2",
"selected": false,
"disabled": false
}
]
}
]
}
}
```
## With Label
Pair a `Select` with a `Label` in a `Column` for a standard form field pattern:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Column, Label, Select, SelectOption
with Column(gap=2, css_class="w-fit mx-auto"):
Label("Preferred language")
with Select(placeholder="Choose language"):
SelectOption(value="en", label="English")
SelectOption(value="es", label="Spanish")
SelectOption(value="fr", label="French")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-2 w-fit mx-auto",
"type": "Column",
"children": [
{"type": "Label", "text": "Preferred language", "optional": false},
{
"name": "select_6",
"type": "Select",
"placeholder": "Choose language",
"size": "default",
"disabled": false,
"required": false,
"invalid": false,
"children": [
{
"type": "SelectOption",
"value": "en",
"label": "English",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "es",
"label": "Spanish",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "fr",
"label": "French",
"selected": false,
"disabled": false
}
]
}
]
}
}
```
## Disabled State
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Select, SelectOption
with Select(
placeholder="Travel class...",
disabled=True,
css_class="w-fit mx-auto",
):
SelectOption(value="first", label="First Class")
SelectOption(value="business", label="Business")
SelectOption(value="economy", label="Economy")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "w-fit mx-auto",
"name": "select_7",
"type": "Select",
"placeholder": "Travel class...",
"size": "default",
"disabled": true,
"required": false,
"invalid": false,
"children": [
{
"type": "SelectOption",
"value": "first",
"label": "First Class",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "business",
"label": "Business",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "economy",
"label": "Economy",
"selected": false,
"disabled": false
}
]
}
}
```
## Disabled Options
Individual options can be disabled while the rest of the dropdown remains interactive. Disabled options appear dimmed and cannot be selected:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Select, SelectOption
with Select(
placeholder="Choose a ship...",
css_class="w-fit mx-auto",
):
SelectOption(value="heart_of_gold", label="Heart of Gold")
SelectOption(
value="bistromath",
label="Bistromath",
disabled=True,
)
SelectOption(value="vogon_ship", label="Vogon Constructor Fleet")
SelectOption(
value="starship_titanic",
label="Starship Titanic",
disabled=True,
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "w-fit mx-auto",
"name": "select_8",
"type": "Select",
"placeholder": "Choose a ship...",
"size": "default",
"disabled": false,
"required": false,
"invalid": false,
"children": [
{
"type": "SelectOption",
"value": "heart_of_gold",
"label": "Heart of Gold",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "bistromath",
"label": "Bistromath",
"selected": false,
"disabled": true
},
{
"type": "SelectOption",
"value": "vogon_ship",
"label": "Vogon Constructor Fleet",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "starship_titanic",
"label": "Starship Titanic",
"selected": false,
"disabled": true
}
]
}
}
```
## Invalid State
Set `invalid=True` to flag a select with error styling. Pair it with a `Label` in a form layout to signal that a selection is required or incorrect:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Column, Label, Select, SelectOption
with Column(gap=2, css_class="w-fit mx-auto"):
Label("Destination")
with Select(placeholder="Choose a planet...", invalid=True):
SelectOption(value="magrathea", label="Magrathea")
SelectOption(value="betelgeuse", label="Betelgeuse V")
SelectOption(value="vogsphere", label="Vogsphere")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-2 w-fit mx-auto",
"type": "Column",
"children": [
{"type": "Label", "text": "Destination", "optional": false},
{
"name": "select_9",
"type": "Select",
"placeholder": "Choose a planet...",
"size": "default",
"disabled": false,
"required": false,
"invalid": true,
"children": [
{
"type": "SelectOption",
"value": "magrathea",
"label": "Magrathea",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "betelgeuse",
"label": "Betelgeuse V",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "vogsphere",
"label": "Vogsphere",
"selected": false,
"disabled": false
}
]
}
]
}
}
```
## Option Groups
Organize long option lists into labeled sections with `SelectGroup` and `SelectLabel`. Use `SelectSeparator` to add visual dividers between groups:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import (
Select,
SelectGroup,
SelectLabel,
SelectOption,
SelectSeparator,
)
with Select(placeholder="Choose a food...", css_class="w-fit"):
with SelectGroup():
SelectLabel("Fruits")
SelectOption(value="apple", label="Apple")
SelectOption(value="banana", label="Banana")
SelectOption(value="cherry", label="Cherry")
SelectSeparator()
with SelectGroup():
SelectLabel("Vegetables")
SelectOption(value="carrot", label="Carrot")
SelectOption(value="broccoli", label="Broccoli")
SelectOption(value="spinach", label="Spinach")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "w-fit",
"name": "select_10",
"type": "Select",
"placeholder": "Choose a food...",
"size": "default",
"disabled": false,
"required": false,
"invalid": false,
"children": [
{
"type": "SelectGroup",
"children": [
{"type": "SelectLabel", "label": "Fruits"},
{
"type": "SelectOption",
"value": "apple",
"label": "Apple",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "banana",
"label": "Banana",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "cherry",
"label": "Cherry",
"selected": false,
"disabled": false
}
]
},
{"type": "SelectSeparator"},
{
"type": "SelectGroup",
"children": [
{"type": "SelectLabel", "label": "Vegetables"},
{
"type": "SelectOption",
"value": "carrot",
"label": "Carrot",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "broccoli",
"label": "Broccoli",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "spinach",
"label": "Spinach",
"selected": false,
"disabled": false
}
]
}
]
}
}
```
## Reading the Value
Use `.rx` to get a reactive reference to the selected option's `value` string. When the user picks an option, anything bound to `.rx` updates automatically:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Column, Select, SelectOption, Text
with Column(gap=4, css_class="w-fit mx-auto"):
with Select(placeholder="Choose a planet...") as sel:
SelectOption(value="magrathea", label="Magrathea")
SelectOption(value="betelgeuse", label="Betelgeuse V")
SelectOption(value="vogsphere", label="Vogsphere")
SelectOption(value="earth", label="Earth (Mostly Harmless)")
Text(f"You chose: {sel.rx}")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-4 w-fit mx-auto",
"type": "Column",
"children": [
{
"name": "select_11",
"type": "Select",
"placeholder": "Choose a planet...",
"size": "default",
"disabled": false,
"required": false,
"invalid": false,
"children": [
{
"type": "SelectOption",
"value": "magrathea",
"label": "Magrathea",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "betelgeuse",
"label": "Betelgeuse V",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "vogsphere",
"label": "Vogsphere",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "earth",
"label": "Earth (Mostly Harmless)",
"selected": false,
"disabled": false
}
]
},
{"content": "You chose: {{ select_11 }}", "type": "Text"}
]
}
}
```
Pick an option and the text updates instantly. The `.rx` reference holds the `value` string of whichever option is selected -- `"magrathea"`, `"betelgeuse"`, etc. -- not the display label.
## Actions
The `on_change` parameter fires actions when the selection changes. Inside the action, `$event` holds the newly selected `value` string:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Column, Select, SelectOption, Text
from prefab_ui.actions import SetState
with Column(gap=4, css_class="w-fit mx-auto"):
with Select(
placeholder="Pick a color...",
on_change=SetState("picked", "You chose: {{ $event }}"),
):
SelectOption(value="red", label="Red")
SelectOption(value="green", label="Green")
SelectOption(value="blue", label="Blue")
Text(
"{{ picked | default:'Make a selection' }}",
css_class="text-muted-foreground",
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-4 w-fit mx-auto",
"type": "Column",
"children": [
{
"name": "select_12",
"type": "Select",
"placeholder": "Pick a color...",
"size": "default",
"disabled": false,
"required": false,
"invalid": false,
"onChange": {"action": "setState", "key": "picked", "value": "You chose: {{ $event }}"},
"children": [
{
"type": "SelectOption",
"value": "red",
"label": "Red",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "green",
"label": "Green",
"selected": false,
"disabled": false
},
{
"type": "SelectOption",
"value": "blue",
"label": "Blue",
"selected": false,
"disabled": false
}
]
},
{
"cssClass": "text-muted-foreground",
"content": "{{ picked | default:'Make a selection' }}",
"type": "Text"
}
]
}
}
```
This is different from `.rx` -- here we're transforming the value before storing it (prepending "You chose: "). For simple "show the current selection" cases, `.rx` is the better approach.
## API Reference
Placeholder text shown when no option is selected.
State key for the selected value. Auto-generated if not provided.
Select size: `"default"`, `"sm"`.
Which side of the trigger the dropdown appears on: `"top"`, `"right"`, `"bottom"`, `"left"`.
Alignment of the dropdown relative to the trigger: `"start"`, `"center"`, `"end"`.
Whether the select is non-interactive.
Whether a selection is required for form submission.
Whether the select shows error styling (red border).
Action(s) to execute when the selection changes. `$event` is the `value` string of the selected option.
Additional Tailwind CSS classes.
Additional Tailwind CSS classes.
Display text for the group header.
Additional Tailwind CSS classes.
Additional Tailwind CSS classes.
The value stored in state when this option is selected.
Display text shown to the user.
Whether this option is initially selected.
Whether this option is non-interactive.
Additional Tailwind CSS classes.
## Protocol Reference
```json Select theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "Select",
"id?": "string",
"onMount?": "any",
"children?": "[Component]",
"let?": "object",
"name?": "string",
"value?": "string",
"placeholder?": "string",
"size?": "sm | default",
"side?": "top | right | bottom | left",
"align?": "start | center | end",
"disabled?": false,
"required?": false,
"invalid?": false,
"onChange?": "Action | Action[]",
"cssClass?": "string"
}
```
```json SelectGroup theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "SelectGroup",
"id?": "string",
"onMount?": "any",
"children?": "[Component]",
"let?": "object",
"cssClass?": "string"
}
```
```json SelectLabel theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "SelectLabel",
"id?": "string",
"onMount?": "any",
"label": "string (required)",
"cssClass?": "string"
}
```
```json SelectSeparator theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "SelectSeparator",
"id?": "string",
"onMount?": "any",
"cssClass?": "string"
}
```
```json SelectOption theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "SelectOption",
"id?": "string",
"onMount?": "any",
"value": "string (required)",
"label": "string (required)",
"selected?": false,
"disabled?": false,
"cssClass?": "string"
}
```
For the complete protocol schema, see [Select](/protocol/select), [SelectGroup](/protocol/select-group), [SelectLabel](/protocol/select-label), [SelectSeparator](/protocol/select-separator), [SelectOption](/protocol/select-option).