> ## 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.
# Combobox
> Searchable dropdown for selecting 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}
;
};
Combobox is a searchable select — a dropdown that lets users type to filter through options. Useful when the list of choices is large enough that scrolling alone would be tedious.
## Basic Usage
A `Combobox` is a container for `ComboboxOption` children. The label can be passed as a positional argument; the `value` is what gets stored in state when that option is selected:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Combobox, ComboboxOption
with Combobox(placeholder="Search planets...", css_class="w-fit mx-auto"):
ComboboxOption("Magrathea", value="magrathea")
ComboboxOption("Betelgeuse V", value="betelgeuse")
ComboboxOption("Vogsphere", value="vogsphere")
ComboboxOption("Krikkit", value="krikkit")
ComboboxOption("Earth", value="earth")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "w-fit mx-auto",
"name": "combobox_1",
"type": "Combobox",
"placeholder": "Search planets...",
"disabled": false,
"invalid": false,
"children": [
{
"type": "ComboboxOption",
"value": "magrathea",
"label": "Magrathea",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "betelgeuse",
"label": "Betelgeuse V",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "vogsphere",
"label": "Vogsphere",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "krikkit",
"label": "Krikkit",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "earth",
"label": "Earth",
"disabled": false
}
]
}
}
```
## Reading the Value
Use `.rx` to get a reactive reference to the selected option's value string. Embed it in other components to display the current selection:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Column, Combobox, ComboboxOption, Text
with Column(gap=3, css_class="w-fit mx-auto"):
with Combobox(placeholder="Search planets...") as combo:
ComboboxOption("Magrathea", value="magrathea")
ComboboxOption("Betelgeuse V", value="betelgeuse")
ComboboxOption("Vogsphere", value="vogsphere")
ComboboxOption("Krikkit", value="krikkit")
Text(f"Selected: {combo.rx}")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-3 w-fit mx-auto",
"type": "Column",
"children": [
{
"name": "combobox_2",
"type": "Combobox",
"placeholder": "Search planets...",
"disabled": false,
"invalid": false,
"children": [
{
"type": "ComboboxOption",
"value": "magrathea",
"label": "Magrathea",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "betelgeuse",
"label": "Betelgeuse V",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "vogsphere",
"label": "Vogsphere",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "krikkit",
"label": "Krikkit",
"disabled": false
}
]
},
{"content": "Selected: {{ combobox_2 }}", "type": "Text"}
]
}
}
```
Search for an option and select it -- the text updates instantly to show the selected value.
## Search Placeholder
The `search_placeholder` parameter customizes the hint text inside the search input that appears when the dropdown opens:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Combobox, ComboboxOption
with Combobox(
placeholder="Choose a ship...",
search_placeholder="Filter by name...",
css_class="w-fit mx-auto",
):
ComboboxOption("Heart of Gold", value="heart-of-gold")
ComboboxOption("Bistromath", value="bistromath")
ComboboxOption("Starship Titanic", value="starship-titanic")
ComboboxOption("Vogon Constructor Fleet", value="vogon-fleet")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "w-fit mx-auto",
"name": "combobox_3",
"type": "Combobox",
"placeholder": "Choose a ship...",
"searchPlaceholder": "Filter by name...",
"disabled": false,
"invalid": false,
"children": [
{
"type": "ComboboxOption",
"value": "heart-of-gold",
"label": "Heart of Gold",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "bistromath",
"label": "Bistromath",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "starship-titanic",
"label": "Starship Titanic",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "vogon-fleet",
"label": "Vogon Constructor Fleet",
"disabled": false
}
]
}
}
```
## With Label
Pair a `Combobox` 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, Combobox, ComboboxOption, Label
with Column(gap=2, css_class="w-fit mx-auto"):
Label("Destination")
with Combobox(placeholder="Search planets..."):
ComboboxOption("Magrathea", value="magrathea")
ComboboxOption("Betelgeuse V", value="betelgeuse")
ComboboxOption("Vogsphere", value="vogsphere")
ComboboxOption("Krikkit", value="krikkit")
```
```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": "combobox_4",
"type": "Combobox",
"placeholder": "Search planets...",
"disabled": false,
"invalid": false,
"children": [
{
"type": "ComboboxOption",
"value": "magrathea",
"label": "Magrathea",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "betelgeuse",
"label": "Betelgeuse V",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "vogsphere",
"label": "Vogsphere",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "krikkit",
"label": "Krikkit",
"disabled": false
}
]
}
]
}
}
```
## Disabled State
A disabled combobox is non-interactive — the trigger button is grayed out and the dropdown won't open:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Combobox, ComboboxOption
with Combobox(
placeholder="Search planets...",
disabled=True,
css_class="w-fit mx-auto",
):
ComboboxOption("Magrathea", value="magrathea")
ComboboxOption("Betelgeuse V", value="betelgeuse")
ComboboxOption("Vogsphere", value="vogsphere")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "w-fit mx-auto",
"name": "combobox_5",
"type": "Combobox",
"placeholder": "Search planets...",
"disabled": true,
"invalid": false,
"children": [
{
"type": "ComboboxOption",
"value": "magrathea",
"label": "Magrathea",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "betelgeuse",
"label": "Betelgeuse V",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "vogsphere",
"label": "Vogsphere",
"disabled": false
}
]
}
}
```
## Disabled Options
Individual options can be disabled while the rest remain selectable. Disabled options still appear in the list but can't be chosen — useful for options that exist but aren't currently available:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Combobox, ComboboxOption
with Combobox(placeholder="Select a planet...", css_class="w-fit mx-auto"):
ComboboxOption("Magrathea", value="magrathea")
ComboboxOption("Earth", value="earth", disabled=True)
ComboboxOption("Betelgeuse", value="betelgeuse")
ComboboxOption("Vogsphere", value="vogsphere")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "w-fit mx-auto",
"name": "combobox_6",
"type": "Combobox",
"placeholder": "Select a planet...",
"disabled": false,
"invalid": false,
"children": [
{
"type": "ComboboxOption",
"value": "magrathea",
"label": "Magrathea",
"disabled": false
},
{"type": "ComboboxOption", "value": "earth", "label": "Earth", "disabled": true},
{
"type": "ComboboxOption",
"value": "betelgeuse",
"label": "Betelgeuse",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "vogsphere",
"label": "Vogsphere",
"disabled": false
}
]
}
}
```
## Invalid State
Set `invalid=True` to indicate a validation error. The trigger shows a red border, making it clear the user needs to correct their selection. Pair it with a `Label` and error text for a complete form field:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Column, Combobox, ComboboxOption, Label, Text
with Column(gap=2, css_class="w-fit mx-auto"):
Label("Home planet")
with Combobox(placeholder="Select a planet...", invalid=True):
ComboboxOption("Magrathea", value="magrathea")
ComboboxOption("Betelgeuse V", value="betelgeuse")
ComboboxOption("Vogsphere", value="vogsphere")
Text(
"Please select your home planet",
css_class="text-sm text-destructive",
)
```
```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": "Home planet", "optional": false},
{
"name": "combobox_7",
"type": "Combobox",
"placeholder": "Select a planet...",
"disabled": false,
"invalid": true,
"children": [
{
"type": "ComboboxOption",
"value": "magrathea",
"label": "Magrathea",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "betelgeuse",
"label": "Betelgeuse V",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "vogsphere",
"label": "Vogsphere",
"disabled": false
}
]
},
{
"cssClass": "text-sm text-destructive",
"content": "Please select your home planet",
"type": "Text"
}
]
}
}
```
## Separators
Use `ComboboxSeparator` to add visual dividers between flat options without needing full group containers. Separators are lightweight — they just draw a line to create logical sections:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Combobox, ComboboxOption, ComboboxSeparator
with Combobox(placeholder="Pick one...", css_class="w-fit mx-auto"):
ComboboxOption("Earth", value="earth")
ComboboxOption("Mars", value="mars")
ComboboxSeparator()
ComboboxOption("Jupiter", value="jupiter")
ComboboxOption("Saturn", value="saturn")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "w-fit mx-auto",
"name": "combobox_8",
"type": "Combobox",
"placeholder": "Pick one...",
"disabled": false,
"invalid": false,
"children": [
{
"type": "ComboboxOption",
"value": "earth",
"label": "Earth",
"disabled": false
},
{"type": "ComboboxOption", "value": "mars", "label": "Mars", "disabled": false},
{"type": "ComboboxSeparator"},
{
"type": "ComboboxOption",
"value": "jupiter",
"label": "Jupiter",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "saturn",
"label": "Saturn",
"disabled": false
}
]
}
}
```
## Option Groups
Organize related options with `ComboboxGroup` and `ComboboxLabel`. Each group gets a non-selectable header label, and groups are automatically separated by dividers in the dropdown:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import (
Combobox,
ComboboxGroup,
ComboboxLabel,
ComboboxOption,
)
with Combobox(
placeholder="Choose a destination...",
css_class="w-fit mx-auto",
):
with ComboboxGroup():
ComboboxLabel("Inner Planets")
ComboboxOption("Magrathea", value="magrathea")
ComboboxOption("Vogsphere", value="vogsphere")
ComboboxOption("Earth", value="earth")
with ComboboxGroup():
ComboboxLabel("Outer Reaches")
ComboboxOption("Betelgeuse V", value="betelgeuse")
ComboboxOption("Krikkit", value="krikkit")
ComboboxOption("Lamuella", value="lamuella")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "w-fit mx-auto",
"name": "combobox_9",
"type": "Combobox",
"placeholder": "Choose a destination...",
"disabled": false,
"invalid": false,
"children": [
{
"type": "ComboboxGroup",
"children": [
{"type": "ComboboxLabel", "label": "Inner Planets"},
{
"type": "ComboboxOption",
"value": "magrathea",
"label": "Magrathea",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "vogsphere",
"label": "Vogsphere",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "earth",
"label": "Earth",
"disabled": false
}
]
},
{
"type": "ComboboxGroup",
"children": [
{"type": "ComboboxLabel", "label": "Outer Reaches"},
{
"type": "ComboboxOption",
"value": "betelgeuse",
"label": "Betelgeuse V",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "krikkit",
"label": "Krikkit",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "lamuella",
"label": "Lamuella",
"disabled": false
}
]
}
]
}
}
```
## 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, Combobox, ComboboxOption, Text
from prefab_ui.actions import SetState
with Column(gap=4, css_class="w-fit mx-auto"):
with Combobox(
placeholder="Choose a ship...",
on_change=SetState(
"ship_status",
"Boarding: {{ $event }}",
),
):
ComboboxOption("Heart of Gold", value="heart-of-gold")
ComboboxOption("Bistromath", value="bistromath")
ComboboxOption("Starship Titanic", value="starship-titanic")
Text(
"{{ ship_status | default:'No ship selected' }}",
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": "combobox_10",
"type": "Combobox",
"placeholder": "Choose a ship...",
"disabled": false,
"invalid": false,
"onChange": {"action": "setState", "key": "ship_status", "value": "Boarding: {{ $event }}"},
"children": [
{
"type": "ComboboxOption",
"value": "heart-of-gold",
"label": "Heart of Gold",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "bistromath",
"label": "Bistromath",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "starship-titanic",
"label": "Starship Titanic",
"disabled": false
}
]
},
{
"cssClass": "text-muted-foreground",
"content": "{{ ship_status | default:'No ship selected' }}",
"type": "Text"
}
]
}
}
```
This is different from `.rx` — here we're transforming the value before storing it (prepending "Boarding: "). For simple "show the current selection" cases, `.rx` is the better approach.
## Side and Align
Control where the dropdown appears relative to the trigger with `side` and `align`. This is useful when the combobox is near the edge of a viewport or inside a constrained layout:
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Combobox, ComboboxOption
with Combobox(
placeholder="Choose a ship...",
side="top",
align="end",
css_class="w-fit mx-auto",
):
ComboboxOption("Heart of Gold", value="heart-of-gold")
ComboboxOption("Bistromath", value="bistromath")
ComboboxOption("Starship Titanic", value="starship-titanic")
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "w-fit mx-auto",
"name": "combobox_11",
"type": "Combobox",
"placeholder": "Choose a ship...",
"disabled": false,
"side": "top",
"align": "end",
"invalid": false,
"children": [
{
"type": "ComboboxOption",
"value": "heart-of-gold",
"label": "Heart of Gold",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "bistromath",
"label": "Bistromath",
"disabled": false
},
{
"type": "ComboboxOption",
"value": "starship-titanic",
"label": "Starship Titanic",
"disabled": false
}
]
}
}
```
## API Reference
Text shown when no value is selected.
Placeholder text in the search input.
State key for the selected value.
Whether the combobox is non-interactive.
Whether the combobox is in an error state.
Which side to show the dropdown.
Alignment of the dropdown relative to the trigger.
Action(s) to execute when the selection changes. `$event` is the `value` string of the selected option.
Additional Tailwind CSS classes.
Display text. Can be passed as a positional argument.
Value stored in state when selected. Defaults to a kebab-case version of the label.
Whether this option is non-selectable.
Container for grouping related options. Children should be `ComboboxLabel` and `ComboboxOption` components.
Label text. Can be passed as a positional argument.
Visual divider between options. No parameters.
## Protocol Reference
```json Combobox theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "Combobox",
"id?": "string",
"onMount?": "any",
"children?": "[Component]",
"let?": "object",
"name?": "string",
"value?": "string",
"placeholder?": "string",
"searchPlaceholder?": "string",
"disabled?": false,
"side?": "top | right | bottom | left",
"align?": "start | center | end",
"invalid?": false,
"onChange?": "Action | Action[]",
"cssClass?": "string"
}
```
```json ComboboxOption theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "ComboboxOption",
"id?": "string",
"onMount?": "any",
"value": "string (required)",
"label": "string (required)",
"disabled?": false,
"cssClass?": "string"
}
```
```json ComboboxGroup theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "ComboboxGroup",
"id?": "string",
"onMount?": "any",
"children?": "[Component]",
"let?": "object",
"cssClass?": "string"
}
```
```json ComboboxLabel theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "ComboboxLabel",
"id?": "string",
"onMount?": "any",
"label": "string (required)",
"cssClass?": "string"
}
```
```json ComboboxSeparator theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "ComboboxSeparator",
"id?": "string",
"onMount?": "any",
"cssClass?": "string"
}
```
For the complete protocol schema, see [Combobox](/protocol/combobox), [ComboboxOption](/protocol/combobox-option), [ComboboxGroup](/protocol/combobox-group), [ComboboxLabel](/protocol/combobox-label), [ComboboxSeparator](/protocol/combobox-separator).