---
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":{"name":"combobox_1","type":"Combobox","placeholder":"Search planets...","disabled":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="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQ29tYm9ib3gsIENvbWJvYm94T3B0aW9uCgp3aXRoIENvbWJvYm94KHBsYWNlaG9sZGVyPSJTZWFyY2ggcGxhbmV0cy4uLiIpOgogICAgQ29tYm9ib3hPcHRpb24oIk1hZ3JhdGhlYSIsIHZhbHVlPSJtYWdyYXRoZWEiKQogICAgQ29tYm9ib3hPcHRpb24oIkJldGVsZ2V1c2UgViIsIHZhbHVlPSJiZXRlbGdldXNlIikKICAgIENvbWJvYm94T3B0aW9uKCJWb2dzcGhlcmUiLCB2YWx1ZT0idm9nc3BoZXJlIikKICAgIENvbWJvYm94T3B0aW9uKCJLcmlra2l0IiwgdmFsdWU9ImtyaWtraXQiKQogICAgQ29tYm9ib3hPcHRpb24oIkVhcnRoIiwgdmFsdWU9ImVhcnRoIikK">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Combobox, ComboboxOption

with Combobox(placeholder="Search planets..."):
    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": {
    "name": "combobox_1",
    "type": "Combobox",
    "placeholder": "Search planets...",
    "disabled": 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","type":"Column","children":[{"name":"combobox_2","type":"Combobox","placeholder":"Search planets...","disabled":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):
    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",
    "type": "Column",
    "children": [
      {
        "name": "combobox_2",
        "type": "Combobox",
        "placeholder": "Search planets...",
        "disabled": 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":{"name":"combobox_3","type":"Combobox","placeholder":"Choose a ship...","searchPlaceholder":"Filter by name...","disabled":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...",
):
    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": {
    "name": "combobox_3",
    "type": "Combobox",
    "placeholder": "Choose a ship...",
    "searchPlaceholder": "Filter by name...",
    "disabled": 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>

## 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":{"name":"combobox_4","type":"Combobox","placeholder":"Select a planet...","disabled":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="ZnJvbSBwcmVmYWJfdWkuY29tcG9uZW50cyBpbXBvcnQgQ29tYm9ib3gsIENvbWJvYm94T3B0aW9uCgp3aXRoIENvbWJvYm94KHBsYWNlaG9sZGVyPSJTZWxlY3QgYSBwbGFuZXQuLi4iKToKICAgIENvbWJvYm94T3B0aW9uKCJNYWdyYXRoZWEiLCB2YWx1ZT0ibWFncmF0aGVhIikKICAgIENvbWJvYm94T3B0aW9uKCJFYXJ0aCIsIHZhbHVlPSJlYXJ0aCIsIGRpc2FibGVkPVRydWUpCiAgICBDb21ib2JveE9wdGlvbigiQmV0ZWxnZXVzZSIsIHZhbHVlPSJiZXRlbGdldXNlIikKICAgIENvbWJvYm94T3B0aW9uKCJWb2dzcGhlcmUiLCB2YWx1ZT0idm9nc3BoZXJlIikK">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Combobox, ComboboxOption

with Combobox(placeholder="Select a planet..."):
    ComboboxOption("Magrathea", value="magrathea")
    ComboboxOption("Earth", value="earth", disabled=True)
    ComboboxOption("Betelgeuse", value="betelgeuse")
    ComboboxOption("Vogsphere", value="vogsphere")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "name": "combobox_4",
    "type": "Combobox",
    "placeholder": "Select a planet...",
    "disabled": 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>

## 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="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>

## Protocol Reference

```json Combobox
{
  "type": "Combobox",
  "children?": "[Component]",
  "let?": "object",
  "name?": "string",
  "placeholder?": "string",
  "searchPlaceholder?": "string",
  "disabled?": false,
  "onChange?": "Action | Action[]",
  "cssClass?": "string"
}
```

```json ComboboxOption
{
  "type": "ComboboxOption",
  "value": "string (required)",
  "label": "string (required)",
  "disabled?": false,
  "cssClass?": "string"
}
```

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