# Toggle Button

A toggle button allows users to toggle a selection on or off, providing a way to switch between two states, such as enabling or disabling a feature.

## Example

```python
from deephaven import ui

my_toggle_button_basic = ui.toggle_button("Pin")
```

## UI Recommendations

If you want to represent a binary choice for the user, consider using a [`checkbox`](checkbox.md).

## Content

A toggle button accepts a label, an icon, or both as children.

```python
from deephaven import ui


my_toggle_button = ui.toggle_button(ui.icon("pin"), ui.text("Pin content"))
```

## Accessibility

If no text is passed into the toggle button, and hence, it has no visible label, the `aria_label` prop should be set for accessibility.

```python
from deephaven import ui


my_toggle_button_accessibility_example = ui.toggle_button(
    ui.icon("pin"), aria_label="pin content"
)
```

## Value

A toggle button is 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_toggle_button_value_examples():
    selected, set_selected = ui.use_state(False)
    return [
        ui.text("Toggle Button (uncontrolled)"),
        ui.toggle_button("Pin", default_selected=True, width="90px"),
        ui.text("Toggle Button (controlled)"),
        ui.toggle_button(
            "Pin", is_selected=selected, on_change=set_selected, width="90px"
        ),
    ]


my_toggle_button_value_examples = ui_toggle_button_value_examples()
```

## Events

The `on_change` property is triggered whenever the value in the toggle button group selection is changed.

```python
from deephaven import ui


@ui.component
def ui_toggle_button_on_change_example():
    is_selected, set_is_selected = ui.use_state(False)
    return [
        ui.toggle_button(
            "Pin",
            is_selected=is_selected,
            on_change=set_is_selected,
        ),
        ui.text(
            f"The toggle button is: `{'selected' if is_selected else 'not selected'}`"
        ),
    ]


my_toggle_button_on_change_example = ui_toggle_button_on_change_example()
```

## Quiet state

The `is_quiet` prop makes a toggle button “quiet”. This can be useful when the toggle button and its corresponding styling should not distract users from surrounding content.

```python
from deephaven import ui


my_toggle_button_is_quiet_example = ui.toggle_button(
    "Pin",
    is_quiet=True,
)
```

## Disabled state

The `is_disabled` prop disables a toggle button to prevent user interaction. This is useful when the toggle button should be visible but not available for selection.

```python
from deephaven import ui


my_toggle_button_is_disabled_example = ui.toggle_button(
    "Pin",
    is_disabled=True,
)
```

## Emphasized

The `is_emphasized` prop makes the toggle button the user’s accent color when selected, adding a visual prominence to the selection.

```python
from deephaven import ui


my_toggle_button_is_emphasized_example = ui.toggle_button(
    "Pin",
    is_emphasized=True,
)
```

## Static Color

The `static_color` prop can be used when the toggle button is placed over a colored background.

```python
from deephaven import ui


my_toggle_button_static_color_example = ui.view(
    ui.toggle_button(
        ui.icon("pin"),
        ui.text("Pin content"),
        static_color="white",
    ),
    background_color="blue-700",
    padding="size-500",
)
```

## API Reference

ToggleButtons allow users to toggle a selection on or off, for example switching between two states or modes.

**Returns:** `Element` The rendered toggle button element.

<ParamTable param={{"module_name": "deephaven.ui.", "name": "toggle_button", "parameters": [{"name": "*children", "type": "Any", "description": "The children to render inside the button."}, {"name": "is_emphasized", "type": "bool | None", "description": "Whether the button should be displayed with an emphasized style.", "default": "None"}, {"name": "is_selected", "type": "bool | None", "description": "Whether the button is selected.", "default": "None"}, {"name": "default_selected", "type": "bool | None", "description": "Whether the button is selected by default.", "default": "None"}, {"name": "is_disabled", "type": "bool | None", "description": "Whether the button is disabled.", "default": "None"}, {"name": "auto_focus", "type": "bool | None", "description": "Whether the button should automatically get focus when the page loads.", "default": "None"}, {"name": "is_quiet", "type": "bool | None", "description": "Whether the button should be quiet.", "default": "None"}, {"name": "static_color", "type": "Literal['white', 'black'] | None", "description": "The static color style to apply. Useful when the button appears over a color background.", "default": "None"}, {"name": "type", "type": "Literal['button', 'submit', 'reset']", "description": "The type of button to render. (default: \"button\")", "default": "'button'"}, {"name": "on_change", "type": "Callable[[bool], None] | None", "description": "Handler that is called when the element's selection state changes.", "default": "None"}, {"name": "on_press", "type": "Callable[[PressEvent], None] | None", "description": "Function called when the button is pressed.", "default": "None"}, {"name": "on_press_start", "type": "Callable[[PressEvent], None] | None", "description": "Function called when the button is pressed.", "default": "None"}, {"name": "on_press_end", "type": "Callable[[PressEvent], None] | None", "description": "Function called when a press interaction ends, either over the target or when the pointer leaves the target.", "default": "None"}, {"name": "on_press_up", "type": "Callable[[PressEvent], None] | None", "description": "Function called when the button is released.", "default": "None"}, {"name": "on_press_change", "type": "Callable[[bool], None] | None", "description": "Function called when the press state changes.", "default": "None"}, {"name": "on_focus", "type": "Callable[[FocusEvent], None] | None", "description": "Function called when the button receives focus.", "default": "None"}, {"name": "on_blur", "type": "Callable[[FocusEvent], None] | None", "description": "Function called when the button 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_expanded", "type": "Literal['true', 'false'] | bool | None", "description": "Whether the element is expanded.", "default": "None"}, {"name": "aria_haspopup", "type": "Literal['true', 'false'] | bool | Literal['menu', 'listbox', 'tree', 'grid', 'dialog'] | None", "description": "Whether the element has a popup.", "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_pressed", "type": "Literal['true', 'false'] | bool | Literal['mixed'] | None", "description": "Whether the element is pressed.", "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"}]}} />