Switch
Switches allow users to turn a single option on or off.
Example
from deephaven import ui
my_switch_basic = ui.switch("Low power mode")
UI recommendations
Recommendations for creating switches:
- Emphasized switches are ideal for forms and settings where the switch being noticed is crucial, while non-emphasized switches suit monochrome application panels to maintain focus on the content.
- Use a standalone switch when the context is clear without a text label, such as next to a panel’s title, to enable or disable panel options.
- Use switches for activation and checkboxes for selection; unlike checkboxes, switches cannot have an error state.
- When a switch represents multiple values from other switches, it should initially appear unselected; clicking it will select and unify all values, while a subsequent click will deselect and reset them.
- Switches can only be on or off; for partial states, use a checkbox, as indeterminate switches are not accessible.
Consider using a checkbox
for individual selections or when marking a single item as selected.
Value
Switches are not selected by default. Use the default_selected
prop to set the initial state (uncontrolled) or the is_selected
prop to control the selected state.
from deephaven import ui
@ui.component
def ui_switch_value_examples():
selected, set_selected = ui.use_state(False)
return [
ui.switch("Low power mode (uncontrolled)", default_selected=True),
ui.switch(
"Low power mode (controlled)", is_selected=selected, on_change=set_selected
),
]
my_switch_value_examples = ui_switch_value_examples()
HTML Forms
Switches can support a name
prop for integration with HTML forms, allowing for easy identification of a value on form submission.
from deephaven import ui
my_switch_name_example = ui.form(ui.switch("Low Power Mode", name="power", value="low"))
Labeling
The switch can be labeled by passing in a child. If no label is provided, an aria_label
must be provided to identify the control for accessibility purposes.
from deephaven import ui
@ui.component
def ui_switch_label_examples():
return [
ui.switch("Switch Label", name="value"),
ui.switch(aria_label="Switch Label", name="value"),
]
my_switch_label_examples = ui_switch_label_examples()
Events
The on_change
property is triggered whenever the switch is pressed.
from deephaven import ui
@ui.component
def ui_switch_on_change_example():
selected, set_selected = ui.use_state(False)
return [
ui.switch("Switch Label", on_change=set_selected, is_selected=selected),
ui.text(f"The switch is {'on' if selected else 'off'}."),
]
my_switch_on_change_example = ui_switch_on_change_example()
Disabled
Setting the is_disabled
prop disables the switch.
from deephaven import ui
my_switch_is_disabled_example = ui.switch("Switch Label", is_disabled=True)
Emphasized
The is_emphasized
prop makes the switch’s fill color the user’s accent color, adding visual prominence to the selection.
from deephaven import ui
my_switch_is_emphasized_example = ui.switch("Switch Label", is_emphasized=True)
Read only
The is_read_only
prop makes the switch read-only to prevent user interaction. This differs from setting the is_disabled
prop since the switch remains focusable.
from deephaven import ui
my_switch_is_read_only_example = ui.switch(
"Switch Label", is_read_only=True, default_selected=True
)
API Reference
Switches allow users to turn an individual option on or off. They are usually used to activate or deactivate a specific setting.
Returns: Element
The rendered switch element.
Parameters | Type | Default | Description |
---|---|---|---|
*children | Any | The children to render inside the input. | |
is_emphasized | bool | None | None | Whether the input should be displayed with an emphasized style. |
default_selected | bool | None | None | Whether the input is selected by default. |
is_selected | bool | None | None | Whether the input is selected. |
value | str | None | None | THe value of the input element, used when submitting a form. |
is_disabled | bool | None | None | Whether the input is disabled. |
is_read_only | bool | None | None | Whether the input can be selected but not changed by the user. |
auto_focus | bool | None | None | Whether the input should automatically get focus when the page loads. |
is_quiet | bool | None | None | Whether the input should be quiet. |
name | str | None | None | The name of the input, used when submitting a form. |
key | str | None | None | A unique identifier used by React to render elements in a list. |