Select

A dropdown in the theme style. Options are shown with str(), so strings, enums or dataclasses all work, and on_select receives the chosen object.

ui.select · Category: Forms · Full reference →

Preview
Code

pz.row([
    ui.select(["Python", "Rust", "TypeScript"], "Rust", on_select, width=180),
    ui.select(["UTF-8", "Latin-1"], None, on_select, placeholder="Encoding…", width=180),
], spacing=12)

When to use

To pick one of many options when there is no room to show them all (language, theme, encoding).
With two to five short options, Segmented or a Radio group shows them at a glance.

Usage

import pyzed as pz
from pyzed import ui

class Settings(pz.App):
    def __init__(self):
        self.language = "Python"

    def view(self):
        return ui.select(["Python", "Rust", "TypeScript"], self.language,
                         lambda value: setattr(self, "language", value), width=180)

Variants

State

Select: Read-only (no on_select) — Read-only (no on_select)

Size

States and events

on_open and on_close run when the menu opens and closes.

The pz.* widget underneath: no theme, every color and size is yours.

Events

Select has 3 events of its own, listed below. Like every widget it also has the 18 common events (click, double_click, right_click, mouse_enter, drag, key_down, resize…), attached with .on(...): see Events and Events of every component.

Event	Of	Handler gets	When
`on_select`	`ui.select`, `pz.pick_list`	`(item)`	Callable that receives the chosen item.
`on_open`	`ui.select`, `pz.pick_list`	`()`	Sent when the menu opens.
`on_close`	`ui.select`, `pz.pick_list`	`()`	Sent when the menu closes.

Handler gets is what Pyzed passes to your callable: () means nothing. Any handler can also be a message (a value that is not callable), which goes to update().

Handling the events

The same events written three ways. Imperative: methods of the app change self. Declarative: the handlers produce messages and one update() decides. Functional: a pure function draws an immutable state and asks for changes with set_state(...). See Imperative, declarative and functional.

class Settings(pz.App):
    def __init__(self):
        self.language = "Python"
        self.open = False

    def view(self):
        return pz.column([
            ui.select(["Python", "Rust", "TypeScript"], self.language,
                      lambda value: setattr(self, "language", value),       # on_select: the option
                      on_open=lambda: setattr(self, "open", True),
                      on_close=lambda: setattr(self, "open", False), width=180),
            ui.muted("Choosing…" if self.open else f"Language: {self.language}"),
        ], spacing=8)

from dataclasses import dataclass


@dataclass
class Language:
    name: str


class Settings(pz.App):
    language = "Python"

    def update(self, message):
        match message:
            case Language(name):
                self.language = name

    def view(self):
        return ui.select(["Python", "Rust", "TypeScript"], self.language, Language, width=180)

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    language: str = "Python"


def view(state, set_state):
    return ui.select(["Python", "Rust", "TypeScript"], state.language,
                     lambda value: set_state(language=value), width=180)

Tips

Properties and API

`ui.select`

select(
    options,
    selected=None,
    on_select=None,
    *,
    placeholder='Select…',
    width=None,
    size='md',
    disabled=False,
    invalid=False,
    on_open=None,
    on_close=None,
    id=None,
    theme=None,
)

A dropdown with the theme style. Options are displayed with str(), so strings, enums, dataclasses or database models all work; on_select receives the chosen object, not its label.

Property	Default	Description
`options`	required	List of options.
`selected`	`None`	Current option.
`placeholder`	`"Select…"`	Hint text shown when empty.
`width`	`None`	Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion).
`size`	`"md"`	`"sm"`, `"md"` or `"lg"`.
`disabled`	`False`	Greys it out.
`invalid`	`False`	Paints the border in the error color.
`id`	`None`	Stable identifier used to focus or scroll it with a `Command`.
`theme`	`None`	Theme to use instead of the current one (`pyzed.theme.current()`).

Events: on_select, on_open, on_close (events).

Full reference →

`pz.pick_list`

pick_list(
    options,
    selected=None,
    on_select=None,
    *,
    on_open=None,
    on_close=None,
    placeholder=None,
    width=None,
    padding=None,
    text_size=None,
    font=None,
    handle=None,
    handle_size=12.0,
    menu_height=None,
    bg=None,
    color=None,
    placeholder_color=None,
    handle_color=None,
    border_color=None,
    hover_border_color=None,
    radius=None,
    menu_bg=None,
    menu_color=None,
    menu_border_color=None,
    selected_bg=None,
    selected_color=None,
    focus_border_color=None,
    id=None,
)

A dropdown to choose one of options. on_select(option) receives the chosen one. For the themed dropdown use ui.select. It takes the keyboard focus like a text field (a click, Tab or Command.focus(id)) and keeps it after a choice: ↑/↓ then pick the previous or next option without opening it, Home/End the first and last and typing jumps to an option; Enter, Space, Alt+↓ or F4 open the menu, where ↑/↓ move, Enter picks and Esc closes.

Property	Default	Description
`options`	required	List of options.
`selected`	`None`	Current option.
`placeholder`	`None`	Hint text shown when empty.
`width`	`None`	Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion).
`padding`	`None`	Inner padding: `8`, `(vertical, horizontal)` or `(top, right, bottom, left)`.
`text_size`	`None`	Text size.
`font`	`None`	Font family.
`handle`	`None`	Arrow icon character.
`handle_size`	`12.0`	Arrow size.
`menu_height`	`None`	Maximum menu height.
`bg`	`None`	Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`).
`color`	`None`	Text or icon color.
`placeholder_color`	`None`	Placeholder color.
`handle_color`	`None`	Arrow color.
`border_color`	`None`	Border color.
`hover_border_color`	`None`	Border color on hover.
`radius`	`None`	Corner radius: a number or `(top_left, top_right, bottom_right, bottom_left)`.
`menu_bg`	`None`	Menu background.
`menu_color`	`None`	Menu text.
`menu_border_color`	`None`	Menu border.
`selected_bg`	`None`	Background of the highlighted option.
`selected_color`	`None`	Text of the highlighted option.
`focus_border_color`	`None`	Border color while it has the keyboard focus.
`id`	`None`	Stable identifier used to focus or scroll it with a `Command`.