---
title: Combobox
description: Searchable dropdown for selecting from a list of options.
icon: magnifying-glass
---

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

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:

<ComponentPreview json={{"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}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQ29tYm9ib3gsIENvbWJvYm94T3B0aW9uCgp3aXRoIENvbWJvYm94KHBsYWNlaG9sZGVyPSJTZWFyY2ggcGxhbmV0cy4uLiIsIGNzc19jbGFzcz0idy1maXQgbXgtYXV0byIpOgogICAgQ29tYm9ib3hPcHRpb24oIk1hZ3JhdGhlYSIsIHZhbHVlPSJtYWdyYXRoZWEiKQogICAgQ29tYm9ib3hPcHRpb24oIkJldGVsZ2V1c2UgViIsIHZhbHVlPSJiZXRlbGdldXNlIikKICAgIENvbWJvYm94T3B0aW9uKCJWb2dzcGhlcmUiLCB2YWx1ZT0idm9nc3BoZXJlIikKICAgIENvbWJvYm94T3B0aW9uKCJLcmlra2l0IiwgdmFsdWU9ImtyaWtraXQiKQogICAgQ29tYm9ib3hPcHRpb24oIkVhcnRoIiwgdmFsdWU9ImVhcnRoIikK">
<CodeGroup>
```python Python icon="python"
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"
{
  "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
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

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

<ComponentPreview json={{"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"}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
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"
{
  "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"}
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

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:

<ComponentPreview json={{"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}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
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"
{
  "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
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## With Label

Pair a `Combobox` with a `Label` in a `Column` for a standard form field pattern:

<ComponentPreview json={{"view":{"cssClass":"gap-2 w-fit mx-auto","type":"Column","children":[{"type":"Label","text":"Destination"},{"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}]}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
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"
{
  "view": {
    "cssClass": "gap-2 w-fit mx-auto",
    "type": "Column",
    "children": [
      {"type": "Label", "text": "Destination"},
      {
        "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
          }
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Disabled State

A disabled combobox is non-interactive — the trigger button is grayed out and the dropdown won't open:

<ComponentPreview json={{"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}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQ29tYm9ib3gsIENvbWJvYm94T3B0aW9uCgp3aXRoIENvbWJvYm94KAogICAgcGxhY2Vob2xkZXI9IlNlYXJjaCBwbGFuZXRzLi4uIiwKICAgIGRpc2FibGVkPVRydWUsCiAgICBjc3NfY2xhc3M9InctZml0IG14LWF1dG8iLAopOgogICAgQ29tYm9ib3hPcHRpb24oIk1hZ3JhdGhlYSIsIHZhbHVlPSJtYWdyYXRoZWEiKQogICAgQ29tYm9ib3hPcHRpb24oIkJldGVsZ2V1c2UgViIsIHZhbHVlPSJiZXRlbGdldXNlIikKICAgIENvbWJvYm94T3B0aW9uKCJWb2dzcGhlcmUiLCB2YWx1ZT0idm9nc3BoZXJlIikK">
<CodeGroup>
```python Python icon="python"
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"
{
  "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
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

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

<ComponentPreview json={{"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}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQ29tYm9ib3gsIENvbWJvYm94T3B0aW9uCgp3aXRoIENvbWJvYm94KHBsYWNlaG9sZGVyPSJTZWxlY3QgYSBwbGFuZXQuLi4iLCBjc3NfY2xhc3M9InctZml0IG14LWF1dG8iKToKICAgIENvbWJvYm94T3B0aW9uKCJNYWdyYXRoZWEiLCB2YWx1ZT0ibWFncmF0aGVhIikKICAgIENvbWJvYm94T3B0aW9uKCJFYXJ0aCIsIHZhbHVlPSJlYXJ0aCIsIGRpc2FibGVkPVRydWUpCiAgICBDb21ib2JveE9wdGlvbigiQmV0ZWxnZXVzZSIsIHZhbHVlPSJiZXRlbGdldXNlIikKICAgIENvbWJvYm94T3B0aW9uKCJWb2dzcGhlcmUiLCB2YWx1ZT0idm9nc3BoZXJlIikK">
<CodeGroup>
```python Python icon="python"
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"
{
  "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
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

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

<ComponentPreview json={{"view":{"cssClass":"gap-2 w-fit mx-auto","type":"Column","children":[{"type":"Label","text":"Home planet"},{"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"}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
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"
{
  "view": {
    "cssClass": "gap-2 w-fit mx-auto",
    "type": "Column",
    "children": [
      {"type": "Label", "text": "Home planet"},
      {
        "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"
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

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

<ComponentPreview json={{"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}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQ29tYm9ib3gsIENvbWJvYm94T3B0aW9uLCBDb21ib2JveFNlcGFyYXRvcgoKd2l0aCBDb21ib2JveChwbGFjZWhvbGRlcj0iUGljayBvbmUuLi4iLCBjc3NfY2xhc3M9InctZml0IG14LWF1dG8iKToKICAgIENvbWJvYm94T3B0aW9uKCJFYXJ0aCIsIHZhbHVlPSJlYXJ0aCIpCiAgICBDb21ib2JveE9wdGlvbigiTWFycyIsIHZhbHVlPSJtYXJzIikKICAgIENvbWJvYm94U2VwYXJhdG9yKCkKICAgIENvbWJvYm94T3B0aW9uKCJKdXBpdGVyIiwgdmFsdWU9Imp1cGl0ZXIiKQogICAgQ29tYm9ib3hPcHRpb24oIlNhdHVybiIsIHZhbHVlPSJzYXR1cm4iKQo">
<CodeGroup>
```python Python icon="python"
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"
{
  "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
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

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

<ComponentPreview json={{"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}]}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
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"
{
  "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
          }
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Actions

The `on_change` parameter fires actions when the selection changes. Inside the action, `$event` holds the newly selected `value` string:

<ComponentPreview json={{"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"}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
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"
{
  "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"
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

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:

<ComponentPreview json={{"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}]}}} playground="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQ29tYm9ib3gsIENvbWJvYm94T3B0aW9uCgp3aXRoIENvbWJvYm94KAogICAgcGxhY2Vob2xkZXI9IkNob29zZSBhIHNoaXAuLi4iLAogICAgc2lkZT0idG9wIiwKICAgIGFsaWduPSJlbmQiLAogICAgY3NzX2NsYXNzPSJ3LWZpdCBteC1hdXRvIiwKKToKICAgIENvbWJvYm94T3B0aW9uKCJIZWFydCBvZiBHb2xkIiwgdmFsdWU9ImhlYXJ0LW9mLWdvbGQiKQogICAgQ29tYm9ib3hPcHRpb24oIkJpc3Ryb21hdGgiLCB2YWx1ZT0iYmlzdHJvbWF0aCIpCiAgICBDb21ib2JveE9wdGlvbigiU3RhcnNoaXAgVGl0YW5pYyIsIHZhbHVlPSJzdGFyc2hpcC10aXRhbmljIikK">
<CodeGroup>
```python Python icon="python"
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"
{
  "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
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## API Reference

<Card icon="code" title="Combobox Parameters">
<ParamField body="placeholder" type="str | None" default="None">
  Text shown when no value is selected.
</ParamField>

<ParamField body="search_placeholder" type="str | None" default="None">
  Placeholder text in the search input.
</ParamField>

<ParamField body="name" type="str | None" default="None">
  State key for the selected value.
</ParamField>

<ParamField body="disabled" type="bool" default="False">
  Whether the combobox is non-interactive.
</ParamField>

<ParamField body="invalid" type="bool" default="False">
  Whether the combobox is in an error state.
</ParamField>

<ParamField body="side" type="'top' | 'right' | 'bottom' | 'left' | None" default="None">
  Which side to show the dropdown.
</ParamField>

<ParamField body="align" type="'start' | 'center' | 'end' | None" default="None">
  Alignment of the dropdown relative to the trigger.
</ParamField>

<ParamField body="on_change" type="Action | list[Action] | None" default="None">
  Action(s) to execute when the selection changes. `$event` is the `value` string of the selected option.
</ParamField>

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

<Card icon="code" title="ComboboxOption Parameters">
<ParamField body="label" type="str" required>
  Display text. Can be passed as a positional argument.
</ParamField>

<ParamField body="value" type="str" required>
  Value stored in state when selected. Defaults to a kebab-case version of the label.
</ParamField>

<ParamField body="disabled" type="bool" default="False">
  Whether this option is non-selectable.
</ParamField>
</Card>

<Card icon="code" title="ComboboxGroup Parameters">
Container for grouping related options. Children should be `ComboboxLabel` and `ComboboxOption` components.
</Card>

<Card icon="code" title="ComboboxLabel Parameters">
<ParamField body="label" type="str" required>
  Label text. Can be passed as a positional argument.
</ParamField>
</Card>

<Card icon="code" title="ComboboxSeparator Parameters">
Visual divider between options. No parameters.
</Card>

## Protocol Reference

```json Combobox
{
  "type": "Combobox",
  "children?": "[Component]",
  "let?": "object",
  "name?": "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
{
  "type": "ComboboxOption",
  "value": "string (required)",
  "label": "string (required)",
  "disabled?": false,
  "cssClass?": "string"
}
```

```json ComboboxGroup
{
  "type": "ComboboxGroup",
  "children?": "[Component]",
  "cssClass?": "string"
}
```

```json ComboboxLabel
{
  "type": "ComboboxLabel",
  "label": "string (required)",
  "cssClass?": "string"
}
```

```json ComboboxSeparator
{
  "type": "ComboboxSeparator",
  "cssClass?": "string"
}
```

For the complete protocol schema, see [Combobox](/protocol/combobox), [ComboboxOption](/protocol/combobox-option).
