# 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, 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 ( Width, create_layout_config, ) from streamlit.elements.lib.options_selector_utils import ( create_mappings, maybe_coerce_enum, validate_and_sync_value_with_options, ) 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.Radio_pb2 import Radio as RadioProto 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 RadioSerde(Generic[T]): """Serializer/deserializer for Radio widget values. Uses string-based values (formatted option strings) for robust handling of dynamic option changes, similar to SelectboxSerde. """ 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: 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 if len(self.options) == 0: return None # 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: # If no options, there's no valid value - return None if len(self.options) == 0: return None if ui_value is None: return ( self.options[self.default_option_index] if self.default_option_index is not None 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 RadioMixin: @overload def radio( self, label: str, options: Sequence[Never], index: int = 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 args: disabled: bool = False, horizontal: bool = False, captions: Sequence[str] | None = None, label_visibility: LabelVisibility = "visible", width: Width = "content", bind: BindOption = None, persist_state: PersistStateOption = None, ) -> None: ... @overload def radio( self, label: str, options: OptionSequence[T], index: int = 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 args: disabled: bool = False, horizontal: bool = False, captions: Sequence[str] | None = None, label_visibility: LabelVisibility = "visible", width: Width = "content", bind: BindOption = None, persist_state: PersistStateOption = None, ) -> T: ... @overload def radio( self, label: str, options: OptionSequence[T], index: None, 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 args: disabled: bool = False, horizontal: bool = False, captions: Sequence[str] | None = None, label_visibility: LabelVisibility = "visible", width: Width = "content", bind: BindOption = None, persist_state: PersistStateOption = None, ) -> T | None: ... @gather_metrics("radio") def radio( 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 args: disabled: bool = False, horizontal: bool = False, captions: Sequence[str] | None = None, label_visibility: LabelVisibility = "visible", width: Width = "content", bind: BindOption = None, persist_state: PersistStateOption = None, ) -> T | None: r"""Display a radio button widget. Parameters ---------- label : str A short label explaining to the user what this radio group 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. Labels can include markdown as described in the ``label`` parameter. 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 radio 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 radio. 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. 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 radio should respond to value changes. This controls whether or not Streamlit reruns the app when the user interacts with the radio. ``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 or changing the selection with the arrow keys). - ``"ignore"``: Streamlit will not rerun the app when the user commits a new value. The radio 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. disabled : bool An optional boolean that disables the radio button if set to ``True``. The default is ``False``. horizontal : bool An optional boolean, which orients the radio group horizontally. The default is false (vertical buttons). captions : iterable of str or None A list of captions to show below each radio button. If this is ``None`` (default), no captions are shown. Captions are matched to ``options`` by position. To caption only some options, use ``None`` or an empty string for the others. If this list is shorter than ``options``, the remaining options have no caption. Any captions after the last option are ignored. 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. width : "content", "stretch", or int The width of the radio button widget. This can be one of the following: - ``"content"`` (default): The width of the widget matches the width of its content, but doesn't exceed the width of the parent container. - ``"stretch"``: 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 or changing the selection with the arrow keys). 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 -------- >>> import streamlit as st >>> >>> genre = st.radio( ... "What's your favorite movie genre", ... [":rainbow[Comedy]", "***Drama***", "Documentary :movie_camera:"], ... captions=[ ... "Laugh out loud.", ... "Get the popcorn.", ... "Never stop learning.", ... ], ... ) >>> >>> if genre == ":rainbow[Comedy]": ... st.write("You selected comedy.") ... else: ... st.write("You didn't select comedy.") .. output:: https://doc-radio.streamlit.app/ height: 300px To initialize an empty radio widget, use ``None`` as the index value: >>> import streamlit as st >>> >>> genre = st.radio( ... "What's your favorite movie genre", ... [":rainbow[Comedy]", "***Drama***", "Documentary :movie_camera:"], ... index=None, ... ) >>> >>> st.write("You selected:", genre) .. output:: https://doc-radio-empty.streamlit.app/ height: 300px """ ctx = get_script_run_ctx() return self._radio( label=label, options=options, index=index, format_func=format_func, key=key, help=help, on_change=on_change, args=args, kwargs=kwargs, disabled=disabled, horizontal=horizontal, captions=captions, label_visibility=label_visibility, bind=bind, persist_state=persist_state, ctx=ctx, width=width, ) def _radio( 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 args: disabled: bool = False, horizontal: bool = False, label_visibility: LabelVisibility = "visible", captions: Sequence[str] | None = None, bind: BindOption = None, persist_state: PersistStateOption = None, ctx: ScriptRunContext | None = None, width: Width = "content", ) -> T | 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) layout_config = create_layout_config(width=width, allow_content_width=True) opt = convert_anything_to_list(options) check_python_comparable(opt) formatted_options, formatted_option_to_option_index = create_mappings( opt, format_func ) element_id = compute_and_register_element_id( "radio", user_key=key, key_as_main_identity=True, dg=self.dg, label=label, options=formatted_options, index=index, help=help, horizontal=horizontal, captions=captions, width=width, ) if index is not None and not isinstance(index, int): 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) def handle_captions(caption: str | None) -> str: if caption is None: return "" if isinstance(caption, str): return caption raise StreamlitInvalidParameterTypeError( "captions", type(caption).__name__, ["str", "None"], ) 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 radio_proto = RadioProto() radio_proto.id = element_id radio_proto.label = label if index is not None: radio_proto.default = index radio_proto.options[:] = formatted_options radio_proto.form_id = current_form_id(self.dg) radio_proto.horizontal = horizontal radio_proto.disabled = disabled radio_proto.label_visibility.value = get_label_visibility_proto_value( label_visibility ) if captions is not None: radio_proto.captions[:] = map(handle_captions, captions) if help is not None: radio_proto.help = to_help_str(help) # Set query param key if bound if bind == "query-params" and key is not None: radio_proto.query_param_key = str(key) if isinstance(on_change, str) and on_change == "ignore": radio_proto.ignore_rerun = True serde = RadioSerde( 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( radio_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 (e.g., ?size=Random). formatted_options=formatted_options, ) widget_state = maybe_coerce_enum(widget_state, options, opt) # Validate the current value against the new options. # If the value is no longer valid (not in options), reset to default. # This handles the case where options change dynamically and the # previously selected value is no longer available. # Cast to T | None since radio doesn't support accept_new_options, # so string values that aren't in options will be reset to default. current_value, value_needs_reset = validate_and_sync_value_with_options( cast("T | None", widget_state.value), opt, index, key, format_func ) if value_needs_reset or widget_state.value_changed: serialized_value = serde.serialize(current_value) if serialized_value is not None: radio_proto.raw_value = serialized_value radio_proto.set_value = True if ctx: save_for_app_testing(ctx, element_id, format_func) self.dg._enqueue( "radio", radio_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)