SelectBox

Bases: Field

Dropdown-like field widget built on top of Field.

Renders a field with a suffix button that opens a popup list of available items. Selecting an item updates the field value and emits <<Change>>.

Events

<<Change>>: Fired when the selection changes (user or code). Provides event.data with keys: value, prev_value, text.

Attributes:

Name	Type	Description
`entry_widget`	`TextEntryPart`	The underlying entry widget.
`label_widget`	`Label`	The label widget.
`message_widget`	`Label`	The message label widget.
`addons`	`dict[str, Widget]`	Dictionary of inserted addon widgets by name.
`variable`	`Variable`	Tkinter Variable linked to entry text.
`signal`	`Signal`	Signal object for reactive updates.

selected_index `property` `writable`

selected_index

Get or set the selected index.

Returns -1 if the current value is not in the items list. Setting to -1 or None clears the selection.

value `property` `writable`

value

Get or set the selected value.

init

__init__(
    master: Master = None,
    value: str = None,
    items: list[str] = None,
    label: str = None,
    message: str = None,
    allow_custom_values: bool = False,
    show_dropdown_button: bool = True,
    dropdown_button_icon: str = None,
    enable_search: bool = False,
    **kwargs: Unpack[FieldOptions],
)

Create a SelectBox widget.

Parameters:

Name	Type	Description	Default
`master`	`Master`	Parent widget. If None, uses the default root window.	`None`
`value`	`str`	Initial selected value; should typically be present in `items`.	`None`
`items`	`list`	Sequence of string options to present in the popup list.	`None`
`label`	`str`	Optional label text shown above the field.	`None`
`message`	`str`	Optional helper/error message shown below the field.	`None`
`allow_custom_values`	`bool`	If True, the entry is editable so users can type arbitrary values in addition to choosing from the list.	`False`
`show_dropdown_button`	`bool`	If True (default), the dropdown button is shown. This option is ignored if custom values are allowed.	`True`
`dropdown_button_icon`	`str`	The icon to display on the dropdown button.	`None`
`enable_search`	`bool`	If True, allows typing in the entry to filter the popup list. When combined with allow_custom_values=False, the first filtered item is selected when the popup closes. With allow_custom_values=True, any typed value is kept.	`False`

Other Parameters:

Name	Type	Description
`allow_blank`	`bool`	If True, empty input is allowed.
`accent`	`str`	Accent token for styling the focus ring and active border.
`value_format`	`str`	ICU format pattern for parsing/formatting.
`font`	`str`	Font for text display.
`foreground`	`str`	Text color.
`initial_focus`	`bool`	If True, widget receives focus when created.
`justify`	`str`	Text justification ('left', 'center', 'right').
`show_message`	`bool`	If True, displays message text below the field.
`padding`	`str \| int \| tuple`	Padding around the entry widget.
`state`	`str`	The widget state ('normal', 'disabled', 'readonly').
`textvariable`	`Variable`	Tkinter Variable to link with the entry text.
`textsignal`	`Signal`	Signal object for reactive text updates.
`width`	`int`	Width of the entry in characters.
`required`	`bool`	If True, field cannot be empty.

SelectBox

selected_index property writable

value property writable

__init__

selected_index `property` `writable`

value `property` `writable`

init