# Copyright (c) Streamlit Inc. (2018-2022) Snowflake Inc. (2022-2026) # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. from __future__ import annotations from typing import ( TYPE_CHECKING, Any, Generic, Literal, TypeVar, cast, overload, ) from typing_extensions import Never from streamlit.dataframe_util import OptionSequence, convert_anything_to_list from streamlit.elements.lib.form_utils import current_form_id from streamlit.elements.lib.layout_utils import ( WidthWithoutContent, create_layout_config, ) from streamlit.elements.lib.options_selector_utils import ( SelectWidgetFilterMode, create_mappings, maybe_coerce_enum, resolve_value_against_options, validate_select_widget_filter_mode, ) from streamlit.elements.lib.policies import ( check_widget_policies, maybe_raise_label_warnings, ) from streamlit.elements.lib.utils import ( Key, LabelVisibility, compute_and_register_element_id, get_label_visibility_proto_value, save_for_app_testing, to_key, ) from streamlit.errors import ( StreamlitInvalidParameterTypeError, StreamlitValueOutOfRangeError, ) from streamlit.proto.Selectbox_pb2 import Selectbox as SelectboxProto from streamlit.runtime.metrics_util import gather_metrics from streamlit.runtime.scriptrunner import ScriptRunContext, get_script_run_ctx from streamlit.runtime.state import ( BindOption, OnChangeMode, PersistStateOption, WidgetArgs, WidgetCallback, WidgetKwargs, get_session_state, register_widget, validate_on_change_mode, ) from streamlit.string_util import to_help_str from streamlit.type_util import check_python_comparable if TYPE_CHECKING: from collections.abc import Callable, Sequence from streamlit.delta_generator import DeltaGenerator T = TypeVar("T") class SelectboxSerde(Generic[T]): options: Sequence[T] formatted_options: list[str] formatted_option_to_option_index: dict[str, int] default_option_index: int | None format_func: Callable[[Any], str] def __init__( self, options: Sequence[T], *, formatted_options: list[str], formatted_option_to_option_index: dict[str, int], default_option_index: int | None = None, format_func: Callable[[Any], str] = str, ) -> None: """Initialize the SelectboxSerde. We do not store an option_to_formatted_option mapping because the generic options might not be hashable, which would raise a RuntimeError. So we do two lookups: option -> index -> formatted_option[index]. Parameters ---------- options : Sequence[T] The sequence of selectable options. formatted_options : list[str] The string representations of each option. The formatted_options correspond to the options sequence by index. formatted_option_to_option_index : dict[str, int] A mapping from formatted option strings to their corresponding indices in the options sequence. default_option_index : int or None, optional The index of the default option to use when no selection is made. If None, no default option is selected. format_func : Callable[[Any], str], optional Function to format options for comparison. Used to compare values by their string representation instead of using == directly. This is necessary because widget values are deepcopied, and for custom classes without __eq__, the deepcopied instances would fail identity comparison. """ self.options = options self.formatted_options = formatted_options self.formatted_option_to_option_index = formatted_option_to_option_index self.default_option_index = default_option_index self.format_func = format_func def serialize(self, v: T | str | None) -> str | None: if v is None: return None # Note: We don't short-circuit for empty options here because # accept_new_options=True allows user-entered values even with no options. # The normal flow below handles this correctly. # Use format_func to find the formatted option instead of using # index_(self.options, v) which relies on == comparison. This is necessary # because widget values are deepcopied, and for custom classes without # __eq__, the deepcopied instances would fail identity comparison. try: formatted_value = self.format_func(v) except Exception: # format_func failed (e.g., v is a string but format_func expects # an object with specific attributes). Use str(v) to ensure we return # a proper string, not the original object. This handles both cases: # - v is already a string -> str(v) returns it unchanged # - v is a custom object -> str(v) gives its string representation return str(v) if formatted_value in self.formatted_option_to_option_index: return formatted_value # Value not found in options - return the formatted string (not the original # object) to maintain type consistency since serialize() must return str|None return formatted_value def deserialize(self, ui_value: str | None) -> T | str | None: # Note: We don't short-circuit for empty options here because # accept_new_options=True allows user-entered values even with no options. # The normal flow below handles this: ui_value not in options -> return ui_value. # Check if the option is pointing to a generic option type T, # otherwise return the option itself. if ui_value is None: return ( self.options[self.default_option_index] if self.default_option_index is not None and len(self.options) > 0 else None ) option_index = self.formatted_option_to_option_index.get(ui_value) return self.options[option_index] if option_index is not None else ui_value class SelectboxMixin: @overload def selectbox( self, label: str, options: Sequence[Never], # Type for empty or Never-inferred options index: int = 0, format_func: Callable[[Any], str] = str, key: Key | None = None, help: str | None = None, on_change: WidgetCallback | OnChangeMode | None = "rerun", args: WidgetArgs | None = None, kwargs: WidgetKwargs | None = None, *, # keyword-only arguments: placeholder: str | None = None, disabled: bool = False, label_visibility: LabelVisibility = "visible", accept_new_options: Literal[False] = False, filter_mode: SelectWidgetFilterMode = "fuzzy", width: WidthWithoutContent = "stretch", bind: BindOption = None, persist_state: PersistStateOption = None, ) -> None: ... # Returns None if options is empty and accept_new_options is False @overload def selectbox( self, label: str, options: OptionSequence[T], index: int = 0, format_func: Callable[[Any], str] = str, key: Key | None = None, help: str | None = None, on_change: WidgetCallback | OnChangeMode | None = "rerun", args: WidgetArgs | None = None, kwargs: WidgetKwargs | None = None, *, # keyword-only arguments: placeholder: str | None = None, disabled: bool = False, label_visibility: LabelVisibility = "visible", accept_new_options: Literal[False] = False, filter_mode: SelectWidgetFilterMode = "fuzzy", width: WidthWithoutContent = "stretch", bind: BindOption = None, persist_state: PersistStateOption = None, ) -> T: ... @overload def selectbox( self, label: str, options: OptionSequence[T], index: int = 0, format_func: Callable[[Any], str] = str, key: Key | None = None, help: str | None = None, on_change: WidgetCallback | OnChangeMode | None = "rerun", args: WidgetArgs | None = None, kwargs: WidgetKwargs | None = None, *, # keyword-only arguments: placeholder: str | None = None, disabled: bool = False, label_visibility: LabelVisibility = "visible", accept_new_options: Literal[True] = True, filter_mode: SelectWidgetFilterMode = "fuzzy", width: WidthWithoutContent = "stretch", bind: BindOption = None, persist_state: PersistStateOption = None, ) -> T | str: ... @overload def selectbox( self, label: str, options: OptionSequence[T], index: None, format_func: Callable[[Any], str] = str, key: Key | None = None, help: str | None = None, on_change: WidgetCallback | OnChangeMode | None = "rerun", args: WidgetArgs | None = None, kwargs: WidgetKwargs | None = None, *, # keyword-only arguments: placeholder: str | None = None, disabled: bool = False, label_visibility: LabelVisibility = "visible", accept_new_options: Literal[False] = False, filter_mode: SelectWidgetFilterMode = "fuzzy", width: WidthWithoutContent = "stretch", bind: BindOption = None, persist_state: PersistStateOption = None, ) -> T | None: ... @overload def selectbox( self, label: str, options: OptionSequence[T], index: None, format_func: Callable[[Any], str] = str, key: Key | None = None, help: str | None = None, on_change: WidgetCallback | OnChangeMode | None = "rerun", args: WidgetArgs | None = None, kwargs: WidgetKwargs | None = None, *, # keyword-only arguments: placeholder: str | None = None, disabled: bool = False, label_visibility: LabelVisibility = "visible", accept_new_options: Literal[True] = True, filter_mode: SelectWidgetFilterMode = "fuzzy", width: WidthWithoutContent = "stretch", bind: BindOption = None, persist_state: PersistStateOption = None, ) -> T | str | None: ... # A dynamic index: int | None with default accept_new_options=False # returns T | None. This sits before the bool catch-all so checkers # that do not expand int | None (e.g. pyrefly) do not pick up a # spurious | str. mypy expands the union, so CI cannot catch deleting # this overload. See #16630. @overload def selectbox( self, label: str, options: OptionSequence[T], index: int | None = 0, format_func: Callable[[Any], str] = str, key: Key | None = None, help: str | None = None, on_change: WidgetCallback | OnChangeMode | None = "rerun", args: WidgetArgs | None = None, kwargs: WidgetKwargs | None = None, *, # keyword-only arguments: placeholder: str | None = None, disabled: bool = False, label_visibility: LabelVisibility = "visible", accept_new_options: Literal[False] = False, filter_mode: SelectWidgetFilterMode = "fuzzy", width: WidthWithoutContent = "stretch", bind: BindOption = None, persist_state: PersistStateOption = None, ) -> T | None: ... @overload def selectbox( self, label: str, options: OptionSequence[T], index: int | None = 0, format_func: Callable[[Any], str] = str, key: Key | None = None, help: str | None = None, on_change: WidgetCallback | OnChangeMode | None = "rerun", args: WidgetArgs | None = None, kwargs: WidgetKwargs | None = None, *, # keyword-only arguments: placeholder: str | None = None, disabled: bool = False, label_visibility: LabelVisibility = "visible", accept_new_options: bool = False, filter_mode: SelectWidgetFilterMode = "fuzzy", width: WidthWithoutContent = "stretch", bind: BindOption = None, persist_state: PersistStateOption = None, ) -> T | str | None: ... @gather_metrics("selectbox") def selectbox( self, label: str, options: OptionSequence[T], index: int | None = 0, format_func: Callable[[Any], str] = str, key: Key | None = None, help: str | None = None, on_change: WidgetCallback | OnChangeMode | None = "rerun", args: WidgetArgs | None = None, kwargs: WidgetKwargs | None = None, *, # keyword-only arguments: placeholder: str | None = None, disabled: bool = False, label_visibility: LabelVisibility = "visible", accept_new_options: bool = False, filter_mode: SelectWidgetFilterMode = "fuzzy", width: WidthWithoutContent = "stretch", bind: BindOption = None, persist_state: PersistStateOption = None, ) -> T | str | None: r"""Display a select widget. Parameters ---------- label : str A short label explaining to the user what this select widget is for. The label can optionally contain GitHub-flavored Markdown of the following types: Bold, Italics, Strikethroughs, Inline Code, Links, and Images. Images display like icons, with a max height equal to the font height. Unsupported Markdown elements are unwrapped so only their children (text contents) render. Common block-level Markdown (headings, lists, blockquotes) is automatically escaped and displays as literal text in labels. See the ``body`` parameter of |st.markdown|_ for additional, supported Markdown directives. For accessibility reasons, you should never set an empty label, but you can hide it with ``label_visibility`` if needed. In the future, we may disallow empty labels by raising an exception. .. |st.markdown| replace:: ``st.markdown`` .. _st.markdown: https://docs.streamlit.io/develop/api-reference/text/st.markdown options : Iterable Labels for the select options in an ``Iterable``. This can be a ``list``, ``set``, or anything supported by ``st.dataframe``. If ``options`` is dataframe-like, the first column will be used. Each label will be cast to ``str`` internally by default. index : int or None The index of the preselected option on first render. If ``None``, will initialize empty and return ``None`` until the user selects an option. Defaults to 0 (the first option). format_func : function Function to modify the display of the options. It receives the raw option as an argument and should output the label to be shown for that option. This has no impact on the return value of the command. key : str, int, or None An optional string or integer to use as the unique key for the widget. If this is ``None`` (default), a key will be generated for the widget based on the values of the other parameters. No two widgets may have the same key. Assigning a key stabilizes the widget's identity and preserves its state across reruns even when other parameters change. .. note:: Changing ``accept_new_options`` resets the widget even when a key is provided. A key lets you read or update the widget's value via ``st.session_state[key]``. For more details, see `Widget behavior `_. Additionally, if ``key`` is provided, it will be used as a CSS class name prefixed with ``st-key-``. help : str or None A tooltip that gets displayed next to the widget label. Streamlit only displays the tooltip when ``label_visibility="visible"``. If this is ``None`` (default), no tooltip is displayed. The tooltip can optionally contain GitHub-flavored Markdown, including the Markdown directives described in the ``body`` parameter of ``st.markdown``. on_change : callable, "rerun", "ignore", or None How the selectbox should respond to value changes. This controls whether or not Streamlit reruns the app when the user interacts with the selectbox. ``on_change`` can be one of the following: - ``"rerun"`` (default): Streamlit will rerun the app when the user commits a new value (clicking an option, confirming with Enter, adding a new option when ``accept_new_options=True``, or clearing the value). - ``"ignore"``: Streamlit will not rerun the app when the user commits a new value. The selectbox still updates in the UI. The new value is available on the next rerun triggered by something else, such as another widget interaction. Ignored commits are held in the browser and are lost if the page is refreshed before that rerun, unless ``bind="query-params"`` is set (see ``bind``). Inside ``st.form``, this has no effect: the form already defers all commits until submit. - A ``callable``: Streamlit will rerun the app and execute the ``callable`` as a callback function before the rest of the app. - ``None``: This is the same as ``on_change="rerun"``. This value exists for backwards compatibility and shouldn't be used. args : list or tuple An optional list or tuple of args to pass to the callback. kwargs : dict An optional dict of kwargs to pass to the callback. placeholder : str or None A string to display when no options are selected. If this is ``None`` (default), the widget displays placeholder text based on the widget's configuration: - "Choose an option" is displayed when options are available and ``accept_new_options=False``. - "Choose or add an option" is displayed when options are available and ``accept_new_options=True``. - "Add an option" is displayed when no options are available and ``accept_new_options=True``. - "No options to select" is displayed when no options are available and ``accept_new_options=False``. The widget is also disabled in this case. disabled : bool An optional boolean that disables the selectbox if set to ``True``. The default is ``False``. label_visibility : "visible", "hidden", or "collapsed" The visibility of the label. The default is ``"visible"``. If this is ``"hidden"``, Streamlit displays an empty spacer instead of the label, which can help keep the widget aligned with other widgets. If this is ``"collapsed"``, Streamlit displays no label or spacer. accept_new_options : bool Whether the user can add a selection that isn't included in ``options``. If this is ``False`` (default), the user can only select from the items in ``options``. If this is ``True``, the user can enter a new item that doesn't exist in ``options``. When a user enters a new item, it is returned by the widget as a string. The new item is not added to the widget's drop-down menu. Streamlit will use a case-insensitive match from ``options`` before adding a new item. filter_mode : "fuzzy", "contains", "prefix", or None The matching mode used to filter options while the user types. If this is ``"fuzzy"`` (default), options are matched by in-order subsequence and sorted by match score. If this is ``"contains"``, options are matched by case-insensitive substring. If this is ``"prefix"``, options are matched by case-insensitive prefix. If this is ``None``, typing is disabled and the options are not filtered. ``filter_mode=None`` is incompatible with ``accept_new_options=True``. width : "stretch" or int The width of the selectbox widget. This can be one of the following: - ``"stretch"`` (default): The width of the widget matches the width of the parent container. - An integer specifying the width in pixels: The widget has a fixed width. If the specified width is greater than the width of the parent container, the width of the widget matches the width of the parent container. bind : "query-params" or None Binding mode for syncing the widget's value with a URL query parameter. If this is ``None`` (default), the widget's value is not synced to the URL. When this is set to ``"query-params"``, changes to the widget update the URL, and the widget can be initialized or updated through a query parameter in the URL. This requires ``key`` to be set. The key is used as the query parameter name. When the widget's value equals its default, the query parameter is removed from the URL to keep it clean. A bound query parameter can't be set or deleted through ``st.query_params``; it can only be programmatically changed through ``st.session_state``. Invalid query parameter values are ignored and removed from the URL. If ``index`` is ``None``, an empty query parameter (e.g., ``?my_key=``) clears the widget. When ``on_change="ignore"``, the URL is updated as soon as the value is committed (clicking an option, confirming with Enter, adding a new option, or clearing the value); typing or filtering alone does not update it. As with widgets inside a form, the URL can show a value that Python hasn't received yet. Python receives the new value on the next rerun, so a page load or share uses the updated URL value. persist_state : "page", "session", or None How long to preserve the widget's value when it isn't rendered. If this is ``None`` (default), the value is lost when the widget stops being rendered or the user switches pages. If this is ``"page"``, the value is preserved only while the user stays on the page where the widget is defined (for example, while the widget is conditionally hidden); it is discarded on a page switch and is not restored if the user returns to the page. If this is ``"session"``, the value is preserved for the entire session, including across page switches, so it returns when the user navigates back. This requires ``key`` to be set. If ``bind="query-params"`` is also set, the binding takes precedence: the value is stored in the URL, so it persists across page switches regardless of the ``persist_state`` scope. Returns ------- any The selected option or ``None`` if no option is selected. This is a copy of the selected option, not the original. Examples -------- **Example 1: Use a basic selectbox widget** If no index is provided, the first option is selected by default. >>> import streamlit as st >>> >>> option = st.selectbox( ... "How would you like to be contacted?", ... ("Email", "Home phone", "Mobile phone"), ... ) >>> >>> st.write("You selected:", option) .. output:: https://doc-selectbox.streamlit.app/ height: 320px **Example 2: Use a selectbox widget with no initial selection** To initialize an empty selectbox, use ``None`` as the index value. >>> import streamlit as st >>> >>> option = st.selectbox( ... "How would you like to be contacted?", ... ("Email", "Home phone", "Mobile phone"), ... index=None, ... placeholder="Select contact method...", ... ) >>> >>> st.write("You selected:", option) .. output:: https://doc-selectbox-empty.streamlit.app/ height: 320px **Example 3: Let users add a new option** To allow users to add a new option that isn't included in the ``options`` list, use the ``accept_new_options=True`` parameter. You can also customize the placeholder text. >>> import streamlit as st >>> >>> option = st.selectbox( ... "Default email", ... ["foo@example.com", "bar@example.com", "baz@example.com"], ... index=None, ... placeholder="Select a saved email or enter a new one", ... accept_new_options=True, ... ) >>> >>> st.write("You selected:", option) .. output:: https://doc-selectbox-accept-new-options.streamlit.app/ height: 320px """ ctx = get_script_run_ctx() return self._selectbox( label=label, options=options, index=index, format_func=format_func, key=key, help=help, on_change=on_change, args=args, kwargs=kwargs, placeholder=placeholder, disabled=disabled, label_visibility=label_visibility, accept_new_options=accept_new_options, filter_mode=filter_mode, width=width, bind=bind, persist_state=persist_state, ctx=ctx, ) def _selectbox( self, label: str, options: OptionSequence[T], index: int | None = 0, format_func: Callable[[Any], Any] = str, key: Key | None = None, help: str | None = None, on_change: WidgetCallback | OnChangeMode | None = "rerun", args: WidgetArgs | None = None, kwargs: WidgetKwargs | None = None, *, # keyword-only arguments: placeholder: str | None = None, disabled: bool = False, label_visibility: LabelVisibility = "visible", accept_new_options: bool = False, filter_mode: SelectWidgetFilterMode = "fuzzy", width: WidthWithoutContent = "stretch", bind: BindOption = None, persist_state: PersistStateOption = None, ctx: ScriptRunContext | None = None, ) -> T | str | None: key = to_key(key) on_change_callback = validate_on_change_mode( on_change, supported_modes=("rerun", "ignore"), ) check_widget_policies( self.dg, key, on_change_callback, default_value=None if index == 0 else index, ) label = maybe_raise_label_warnings(label, label_visibility) opt = convert_anything_to_list(options) check_python_comparable(opt) if not isinstance(index, int) and index is not None: raise StreamlitInvalidParameterTypeError( "index", type(index).__name__, ["int", "None"], ) if index is not None and len(opt) > 0 and not 0 <= index < len(opt): raise StreamlitValueOutOfRangeError("index", index, 0, len(opt) - 1) # Convert empty string to single space to distinguish from None: # - None (default) → "" → Frontend shows contextual placeholders # - "" (explicit empty) → " " → Frontend shows empty placeholder # - "Custom" → "Custom" → Frontend shows custom placeholder if placeholder == "": placeholder = " " proto_filter_mode = validate_select_widget_filter_mode( filter_mode, accept_new_options=accept_new_options, ) formatted_options, formatted_option_to_option_index = create_mappings( opt, format_func ) element_id = compute_and_register_element_id( "selectbox", user_key=key, # Treat the provided key as the main identity. Only include # accept_new_options in the identity computation because it can # invalidate the current selection and is complex to support. key_as_main_identity={"accept_new_options"}, dg=self.dg, label=label, options=formatted_options, index=index, help=help, placeholder=placeholder, accept_new_options=accept_new_options, filter_mode=filter_mode, width=width, ) session_state = get_session_state().filtered_state if key is not None and key in session_state and session_state[key] is None: index = None selectbox_proto = SelectboxProto() selectbox_proto.id = element_id selectbox_proto.label = label if index is not None: selectbox_proto.default = index selectbox_proto.options[:] = formatted_options selectbox_proto.form_id = current_form_id(self.dg) selectbox_proto.placeholder = placeholder or "" selectbox_proto.disabled = disabled selectbox_proto.label_visibility.value = get_label_visibility_proto_value( label_visibility ) selectbox_proto.accept_new_options = accept_new_options selectbox_proto.filter_mode = proto_filter_mode if help is not None: selectbox_proto.help = to_help_str(help) # Set query param key if bound if bind == "query-params" and key is not None: selectbox_proto.query_param_key = str(key) if isinstance(on_change, str) and on_change == "ignore": selectbox_proto.ignore_rerun = True serde = SelectboxSerde( opt, formatted_options=formatted_options, formatted_option_to_option_index=formatted_option_to_option_index, default_option_index=index, format_func=format_func, ) widget_state = register_widget( selectbox_proto.id, on_change_handler=on_change_callback, args=args, kwargs=kwargs, deserializer=serde.deserialize, serializer=serde.serialize, ctx=ctx, value_type="string_value", disabled=disabled, bind=bind, persist_state=persist_state, # Clearable when index=None: the widget can be in an empty state, # so ?key= (empty URL param) should clear the widget to None. clearable=(index is None), # Pass formatted_options so _seed_widget_from_url can reject # invalid option strings from URLs. Not passed when # accept_new_options=True since any string is valid. formatted_options=None if accept_new_options else formatted_options, ) widget_state = maybe_coerce_enum(widget_state, options, opt) if accept_new_options: current_value = widget_state.value value_needs_reset = False else: # Reset the selection only if the stored value no longer matches any # option; see resolve_value_against_options for the format_func and # wire-label fallback logic. current_value, value_needs_reset = resolve_value_against_options( widget_state.value, opt, formatted_option_to_option_index, index, key, format_func, widget_state.incoming_serialized_value, ) if value_needs_reset or widget_state.value_changed: serialized_value = serde.serialize(current_value) if serialized_value is not None: selectbox_proto.raw_value = serialized_value selectbox_proto.set_value = True layout_config = create_layout_config(width=width) if ctx: save_for_app_testing(ctx, element_id, format_func) self.dg._enqueue( "selectbox", selectbox_proto, layout_config=layout_config, has_one_shot_effect=value_needs_reset or widget_state.value_changed, ) return current_value @property def dg(self) -> DeltaGenerator: """The associated DeltaGenerator.""" return cast("DeltaGenerator", self)