# Switch

Switches allow users to turn a single option on or off.

## Example

```python
from deephaven import ui

my_switch_basic = ui.switch("Low power mode")
```

## UI recommendations

Recommendations for creating switches:

1. 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.
2. 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.
3. Use switches for activation and checkboxes for selection; unlike checkboxes, switches cannot have an error state.
4. 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.
5. Switches can only be on or off; for partial states, use a checkbox, as indeterminate switches are not accessible.

Consider using a [`checkbox`](checkbox.md) 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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

<ParamTable param={{"module_name": "deephaven.ui.", "name": "switch", "parameters": [{"name": "*children", "type": "Any", "description": "The children to render inside the input."}, {"name": "is_emphasized", "type": "bool | None", "description": "Whether the input should be displayed with an emphasized style.", "default": "None"}, {"name": "default_selected", "type": "bool | None", "description": "Whether the input is selected by default.", "default": "None"}, {"name": "is_selected", "type": "bool | None", "description": "Whether the input is selected.", "default": "None"}, {"name": "value", "type": "str | None", "description": "THe value of the input element, used when submitting a form.", "default": "None"}, {"name": "is_disabled", "type": "bool | None", "description": "Whether the input is disabled.", "default": "None"}, {"name": "is_read_only", "type": "bool | None", "description": "Whether the input can be selected but not changed by the user.", "default": "None"}, {"name": "auto_focus", "type": "bool | None", "description": "Whether the input should automatically get focus when the page loads.", "default": "None"}, {"name": "is_quiet", "type": "bool | None", "description": "Whether the input should be quiet.", "default": "None"}, {"name": "name", "type": "str | None", "description": "The name of the input, used when submitting a form.", "default": "None"}, {"name": "on_change", "type": "Callable[[bool], None] | None", "description": "Handler that is called when the element's selection state changes.", "default": "None"}, {"name": "on_focus", "type": "Callable[[FocusEvent], None] | None", "description": "Function called when the input receives focus.", "default": "None"}, {"name": "on_blur", "type": "Callable[[FocusEvent], None] | None", "description": "Function called when the input loses focus.", "default": "None"}, {"name": "on_focus_change", "type": "Callable[[bool], None] | None", "description": "Function called when the focus state changes.", "default": "None"}, {"name": "on_key_down", "type": "Callable[[KeyboardEvent], None] | None", "description": "Function called when a key is pressed.", "default": "None"}, {"name": "on_key_up", "type": "Callable[[KeyboardEvent], None] | None", "description": "Function called when a key is released.", "default": "None"}, {"name": "flex", "type": "str | float | bool | None", "description": "When used in a flex layout, specifies how the element will grow or shrink to fit the space available.", "default": "None"}, {"name": "flex_grow", "type": "float | None", "description": "When used in a flex layout, specifies how much the element will grow to fit the space available.", "default": "None"}, {"name": "flex_shrink", "type": "float | None", "description": "When used in a flex layout, specifies how much the element will shrink to fit the space available.", "default": "None"}, {"name": "flex_basis", "type": "str | float | None", "description": "When used in a flex layout, specifies the initial size of the element.", "default": "None"}, {"name": "align_self", "type": "Literal['auto', 'normal', 'start', 'end', 'center', 'flex-start', 'flex-end', 'self-start', 'self-end', 'stretch'] | None", "description": "Overrides the align_items property of a flex or grid container.", "default": "None"}, {"name": "justify_self", "type": "Literal['auto', 'normal', 'start', 'end', 'flex-start', 'flex-end', 'self-start', 'self-end', 'center', 'left', 'right', 'stretch'] | None", "description": "Specifies how the element is justified inside a flex or grid container.", "default": "None"}, {"name": "order", "type": "int | None", "description": "The layout order for the element within a flex or grid container.", "default": "None"}, {"name": "grid_area", "type": "str | None", "description": "The name of the grid area to place the element in.", "default": "None"}, {"name": "grid_row", "type": "str | None", "description": "The name of the grid row to place the element in.", "default": "None"}, {"name": "grid_row_start", "type": "str | None", "description": "The name of the grid row to start the element in.", "default": "None"}, {"name": "grid_row_end", "type": "str | None", "description": "The name of the grid row to end the element in.", "default": "None"}, {"name": "grid_column", "type": "str | None", "description": "The name of the grid column to place the element in.", "default": "None"}, {"name": "grid_column_start", "type": "str | None", "description": "The name of the grid column to start the element in.", "default": "None"}, {"name": "grid_column_end", "type": "str | None", "description": "The name of the grid column to end the element in.", "default": "None"}, {"name": "margin", "type": "str | float | None", "description": "The margin to apply around the element.", "default": "None"}, {"name": "margin_top", "type": "str | float | None", "description": "The margin to apply above the element.", "default": "None"}, {"name": "margin_bottom", "type": "str | float | None", "description": "The margin to apply below the element.", "default": "None"}, {"name": "margin_start", "type": "str | float | None", "description": "The margin to apply before the element.", "default": "None"}, {"name": "margin_end", "type": "str | float | None", "description": "The margin to apply after the element.", "default": "None"}, {"name": "margin_x", "type": "str | float | None", "description": "The margin to apply to the left and right of the element.", "default": "None"}, {"name": "margin_y", "type": "str | float | None", "description": "The margin to apply to the top and bottom of the element.", "default": "None"}, {"name": "width", "type": "str | float | None", "description": "The width of the element.", "default": "None"}, {"name": "height", "type": "str | float | None", "description": "The height of the element.", "default": "None"}, {"name": "min_width", "type": "str | float | None", "description": "The minimum width of the element.", "default": "None"}, {"name": "min_height", "type": "str | float | None", "description": "The minimum height of the element.", "default": "None"}, {"name": "max_width", "type": "str | float | None", "description": "The maximum width of the element.", "default": "None"}, {"name": "max_height", "type": "str | float | None", "description": "The maximum height of the element.", "default": "None"}, {"name": "position", "type": "Literal['static', 'relative', 'absolute', 'fixed', 'sticky'] | None", "description": "Specifies how the element is positioned.", "default": "None"}, {"name": "top", "type": "str | float | None", "description": "The distance from the top of the containing element.", "default": "None"}, {"name": "bottom", "type": "str | float | None", "description": "The distance from the bottom of the containing element.", "default": "None"}, {"name": "start", "type": "str | float | None", "description": "The distance from the start of the containing element.", "default": "None"}, {"name": "end", "type": "str | float | None", "description": "The distance from the end of the containing element.", "default": "None"}, {"name": "left", "type": "str | float | None", "description": "The distance from the left of the containing element.", "default": "None"}, {"name": "right", "type": "str | float | None", "description": "The distance from the right of the containing element.", "default": "None"}, {"name": "z_index", "type": "int | None", "description": "The stack order of the element.", "default": "None"}, {"name": "is_hidden", "type": "bool | None", "description": "Whether the element is hidden.", "default": "None"}, {"name": "id", "type": "str | None", "description": "A unique identifier for the element.", "default": "None"}, {"name": "exclude_from_tab_order", "type": "bool | None", "description": "Whether the element should be excluded from the tab order.", "default": "None"}, {"name": "aria_controls", "type": "str | None", "description": "The id of the element that the element controls.", "default": "None"}, {"name": "aria_label", "type": "str | None", "description": "The label for the element.", "default": "None"}, {"name": "aria_labelledby", "type": "str | None", "description": "The id of the element that labels the element.", "default": "None"}, {"name": "aria_describedby", "type": "str | None", "description": "The id of the element that describes the element.", "default": "None"}, {"name": "aria_details", "type": "str | None", "description": "The details for the element.", "default": "None"}, {"name": "UNSAFE_class_name", "type": "str | None", "description": "A CSS class to apply to the element.", "default": "None"}, {"name": "UNSAFE_style", "type": "Dict[str, Any] | None", "description": "A CSS style to apply to the element.", "default": "None"}, {"name": "key", "type": "str | None", "description": "A unique identifier used by React to render elements in a list.", "default": "None"}]}} />