---
title: Select
description: Dropdown select for choosing from a list of options.
icon: square-caret-down
---

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

Select dropdowns let users pick one option from a list.

## Basic Usage

<ComponentPreview json={{"view":{"type":"Select","placeholder":"Choose size...","name":"select-1","size":"default","disabled":false,"required":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}]}}}>
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import (
    Select,
    SelectOption,
)

with Select(placeholder="Choose size..."):
    SelectOption(value="sm", label="Small")
    SelectOption(value="md", label="Medium")
    SelectOption(value="lg", label="Large")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "type": "Select",
    "placeholder": "Choose size...",
    "name": "select-1",
    "size": "default",
    "disabled": false,
    "required": 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
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## With Selected Value

<ComponentPreview json={{"view":{"type":"Select","placeholder":"Select country","name":"select-2","size":"default","disabled":false,"required":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}]}}}>
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import (
    Select,
    SelectOption,
)

with Select(placeholder="Select country"):
    SelectOption(value="us", label="United States")
    SelectOption(value="uk", label="United Kingdom", selected=True)
    SelectOption(value="ca", label="Canada")
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "type": "Select",
    "placeholder": "Select country",
    "name": "select-2",
    "size": "default",
    "disabled": false,
    "required": 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
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Sizes

<ComponentPreview json={{"view":{"cssClass":"gap-4","type":"Column","children":[{"type":"Select","placeholder":"Default size","name":"select-3","size":"default","disabled":false,"required":false,"children":[{"type":"SelectOption","value":"1","label":"Option 1","selected":false,"disabled":false},{"type":"SelectOption","value":"2","label":"Option 2","selected":false,"disabled":false}]},{"type":"Select","placeholder":"Small size","name":"select-4","size":"sm","disabled":false,"required":false,"children":[{"type":"SelectOption","value":"1","label":"Option 1","selected":false,"disabled":false},{"type":"SelectOption","value":"2","label":"Option 2","selected":false,"disabled":false}]}]}}}>
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import (
    Column,
    Select,
    SelectOption,
)

with Column(gap=4):
    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"
{
  "view": {
    "cssClass": "gap-4",
    "type": "Column",
    "children": [
      {
        "type": "Select",
        "placeholder": "Default size",
        "name": "select-3",
        "size": "default",
        "disabled": false,
        "required": false,
        "children": [
          {
            "type": "SelectOption",
            "value": "1",
            "label": "Option 1",
            "selected": false,
            "disabled": false
          },
          {
            "type": "SelectOption",
            "value": "2",
            "label": "Option 2",
            "selected": false,
            "disabled": false
          }
        ]
      },
      {
        "type": "Select",
        "placeholder": "Small size",
        "name": "select-4",
        "size": "sm",
        "disabled": false,
        "required": false,
        "children": [
          {
            "type": "SelectOption",
            "value": "1",
            "label": "Option 1",
            "selected": false,
            "disabled": false
          },
          {
            "type": "SelectOption",
            "value": "2",
            "label": "Option 2",
            "selected": false,
            "disabled": false
          }
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## With Label

<ComponentPreview json={{"view":{"cssClass":"gap-2","type":"Column","children":[{"type":"Label","text":"Preferred language"},{"type":"Select","placeholder":"Choose language","name":"select-5","size":"default","disabled":false,"required":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}]}]}}}>
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import (
    Column,
    Label,
    Select,
    SelectOption,
)

with Column(gap=2):
    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"
{
  "view": {
    "cssClass": "gap-2",
    "type": "Column",
    "children": [
      {"type": "Label", "text": "Preferred language"},
      {
        "type": "Select",
        "placeholder": "Choose language",
        "name": "select-5",
        "size": "default",
        "disabled": false,
        "required": 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
          }
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## With Actions

The `on_change` parameter runs actions when the selection changes. `$event` is the `value` string of the selected option:

<ComponentPreview json={{"view":{"cssClass":"gap-4","type":"Column","children":[{"type":"Select","placeholder":"Pick a color...","name":"select-6","size":"default","disabled":false,"required":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 | 'Make a selection' }}","type":"Text"}]}}}>
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Column, Select, SelectOption, Text
from prefab_ui.actions import SetState

with Column(gap=4):
    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 | 'Make a selection' }}",
        css_class="text-muted-foreground",
    )
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "cssClass": "gap-4",
    "type": "Column",
    "children": [
      {
        "type": "Select",
        "placeholder": "Pick a color...",
        "name": "select-6",
        "size": "default",
        "disabled": false,
        "required": 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 | 'Make a selection' }}",
        "type": "Text"
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## API Reference

<Card icon="code" title="Select Parameters">
<ParamField body="placeholder" type="str | None" default="None">
  Placeholder text shown when no option is selected.
</ParamField>

<ParamField body="name" type="str | None" default="None">
  State key for the selected value. Auto-generated if not provided. Use `.rx` to reference the current selection in other components without specifying the key explicitly.
</ParamField>

<ParamField body="size" type="str" default="default">
  Select size: `"default"`, `"sm"`.
</ParamField>

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

<ParamField body="required" type="bool" default="False">
  Whether a selection is required for form submission.
</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 appended to the component's built-in styles.
</ParamField>
</Card>

<Card icon="code" title="SelectOption Parameters">
<ParamField body="value" type="str" required>
  Option value for form submission.
</ParamField>

<ParamField body="label" type="str" required>
  Display text shown to the user.
</ParamField>

<ParamField body="selected" type="bool" default="False">
  Whether this option is initially selected.
</ParamField>

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

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

## Protocol Reference

```json Select
{
  "type": "Select",
  "children?": "[Component]",
  "let?": "object",
  "placeholder?": "string",
  "name?": "string",
  "size?": "sm | default",
  "disabled?": false,
  "required?": false,
  "onChange?": "Action | Action[]",
  "cssClass?": "string"
}
```

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

For the complete protocol schema, see [Select](/protocol/select), [SelectOption](/protocol/select-option).
