# 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 dataclasses import dataclass from typing import TYPE_CHECKING, cast 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.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, to_key, ) from streamlit.proto.Checkbox_pb2 import Checkbox as CheckboxProto 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, register_widget, validate_on_change_mode, ) from streamlit.string_util import to_help_str if TYPE_CHECKING: from streamlit.delta_generator import DeltaGenerator @dataclass class CheckboxSerde: value: bool def serialize(self, v: bool) -> bool: return bool(v) def deserialize(self, ui_value: bool | None) -> bool: return bool(ui_value if ui_value is not None else self.value) class CheckboxMixin: @gather_metrics("checkbox") def checkbox( self, label: str, value: bool = False, 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: disabled: bool = False, label_visibility: LabelVisibility = "visible", width: Width = "content", wrap: bool | None = None, bind: BindOption = None, persist_state: PersistStateOption = None, ) -> bool: r"""Display a checkbox widget. Parameters ---------- label : str A short label explaining to the user what this checkbox 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 value : bool Preselect the checkbox when it first renders. This will be cast to bool internally. 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 checkbox should respond to value changes. This controls whether or not Streamlit reruns the app when the user interacts with the checkbox. ``on_change`` can be one of the following: - ``"rerun"`` (default): Streamlit will rerun the app when the user clicks the checkbox. - ``"ignore"``: Streamlit will not rerun the app when the user clicks the checkbox. The checkbox 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 checkbox 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. width : "content", "stretch", or int The width of the checkbox 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. wrap : bool or None Whether the checkbox label can wrap onto multiple lines. This can be one of the following: - ``None`` (default): Streamlit decides based on the surrounding layout. Inside a horizontal container or when directly placed in a column (not nested in another container), the checkbox keeps its standard, single-row height and truncates an overflowing label with an ellipsis; in other layouts, the label wraps onto additional lines. - ``True``: If the label is too wide for the checkbox, it wraps onto additional lines and the widget grows taller. - ``False``: The checkbox keeps its standard, single-row height. A label that is too wide is truncated with an ellipsis. When the checkbox keeps a single-row label, hovering the label reveals the full label in a tooltip, including when ``help`` is set. The checkbox indicator and help icon remain visible. 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``. When ``on_change="ignore"``, the URL is updated as soon as the user clicks the checkbox. 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 ------- bool Whether or not the checkbox is checked. Examples -------- >>> import streamlit as st >>> >>> agree = st.checkbox("I agree") >>> >>> if agree: ... st.write("Great!") .. output:: https://doc-checkbox.streamlit.app/ height: 220px """ ctx = get_script_run_ctx() return self._checkbox( label=label, value=value, key=key, help=help, on_change=on_change, args=args, kwargs=kwargs, disabled=disabled, label_visibility=label_visibility, type=CheckboxProto.StyleType.DEFAULT, ctx=ctx, width=width, wrap=wrap, bind=bind, persist_state=persist_state, ) @gather_metrics("toggle") def toggle( self, label: str, value: bool = False, 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: disabled: bool = False, label_visibility: LabelVisibility = "visible", width: Width = "content", wrap: bool | None = None, bind: BindOption = None, persist_state: PersistStateOption = None, ) -> bool: r"""Display a toggle widget. Parameters ---------- label : str A short label explaining to the user what this toggle 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 value : bool Preselect the toggle when it first renders. This will be cast to bool internally. 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 toggle should respond to value changes. This controls whether or not Streamlit reruns the app when the user interacts with the toggle. ``on_change`` can be one of the following: - ``"rerun"`` (default): Streamlit will rerun the app when the user clicks the toggle. - ``"ignore"``: Streamlit will not rerun the app when the user clicks the toggle. The toggle 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 toggle 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. width : "content", "stretch", or int The width of the toggle 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. wrap : bool or None Whether the toggle label can wrap onto multiple lines. This can be one of the following: - ``None`` (default): Streamlit decides based on the surrounding layout. Inside a horizontal container or when directly placed in a column (not nested in another container), the toggle keeps its standard, single-row height and truncates an overflowing label with an ellipsis; in other layouts, the label wraps onto additional lines. - ``True``: If the label is too wide for the toggle, it wraps onto additional lines and the widget grows taller. - ``False``: The toggle keeps its standard, single-row height. A label that is too wide is truncated with an ellipsis. When the toggle keeps a single-row label, hovering the label reveals the full label in a tooltip, including when ``help`` is set. The toggle switch and help icon remain visible. 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``. When ``on_change="ignore"``, the URL is updated as soon as the user clicks the toggle. 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 ------- bool Whether or not the toggle is checked. Examples -------- >>> import streamlit as st >>> >>> on = st.toggle("Activate feature") >>> >>> if on: ... st.write("Feature activated!") .. output:: https://doc-toggle.streamlit.app/ height: 220px """ ctx = get_script_run_ctx() return self._checkbox( label=label, value=value, key=key, help=help, on_change=on_change, args=args, kwargs=kwargs, disabled=disabled, label_visibility=label_visibility, type=CheckboxProto.StyleType.TOGGLE, ctx=ctx, width=width, wrap=wrap, bind=bind, persist_state=persist_state, ) def _checkbox( self, label: str, value: bool = False, 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: disabled: bool = False, label_visibility: LabelVisibility = "visible", type: CheckboxProto.StyleType.ValueType = CheckboxProto.StyleType.DEFAULT, ctx: ScriptRunContext | None = None, width: Width = "content", wrap: bool | None = None, bind: BindOption = None, persist_state: PersistStateOption = None, ) -> bool: 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 value is False else value, ) label = maybe_raise_label_warnings(label, label_visibility) element_id = compute_and_register_element_id( "toggle" if type == CheckboxProto.StyleType.TOGGLE else "checkbox", user_key=key, key_as_main_identity=True, dg=self.dg, label=label, value=bool(value), help=help, width=width, ) checkbox_proto = CheckboxProto() checkbox_proto.id = element_id checkbox_proto.label = label checkbox_proto.default = bool(value) checkbox_proto.type = type checkbox_proto.form_id = current_form_id(self.dg) checkbox_proto.disabled = disabled checkbox_proto.label_visibility.value = get_label_visibility_proto_value( label_visibility ) if help is not None: checkbox_proto.help = to_help_str(help) # wrap is layout-only, so it is intentionally excluded from the element # id above. Leaving it unset lets the frontend resolve the auto default # from the surrounding layout. if wrap is not None: checkbox_proto.wrap = wrap # Set query param key if bound if bind == "query-params" and key is not None: checkbox_proto.query_param_key = str(key) if isinstance(on_change, str) and on_change == "ignore": checkbox_proto.ignore_rerun = True layout_config = create_layout_config(width=width, allow_content_width=True) serde = CheckboxSerde(value) checkbox_state = register_widget( checkbox_proto.id, on_change_handler=on_change_callback, args=args, kwargs=kwargs, deserializer=serde.deserialize, serializer=serde.serialize, ctx=ctx, value_type="bool_value", disabled=disabled, bind=bind, persist_state=persist_state, # Checkbox/toggle is not clearable (always true or false) clearable=False, ) if checkbox_state.value_changed: checkbox_proto.value = checkbox_state.value checkbox_proto.set_value = True self.dg._enqueue( "checkbox", checkbox_proto, layout_config=layout_config, has_one_shot_effect=checkbox_state.value_changed, ) return checkbox_state.value @property def dg(self) -> DeltaGenerator: """The associated DeltaGenerator.""" return cast("DeltaGenerator", self)