Switch

A simple switch widget which stores a boolean value.

• Focusable
• Container

Example

The example below shows switches in various states.

Outputswitch.pyswitch.tcss

from textual.app import App, ComposeResult
from textual.containers import Horizontal
from textual.widgets import Static, Switch


class SwitchApp(App):
    def compose(self) -> ComposeResult:
        yield Static("[b]Example switches\n", classes="label")
        yield Horizontal(
            Static("off:     ", classes="label"),
            Switch(animate=False),
            classes="container",
        )
        yield Horizontal(
            Static("on:      ", classes="label"),
            Switch(value=True),
            classes="container",
        )

        focused_switch = Switch()
        focused_switch.focus()
        yield Horizontal(
            Static("focused: ", classes="label"), focused_switch, classes="container"
        )

        yield Horizontal(
            Static("custom:  ", classes="label"),
            Switch(id="custom-design"),
            classes="container",
        )


app = SwitchApp(css_path="switch.tcss")
if __name__ == "__main__":
    app.run()

Screen {
    align: center middle;
}

.container {
    height: auto;
    width: auto;
}

Switch {
    height: auto;
    width: auto;
}

.label {
    height: 3;
    content-align: center middle;
    width: auto;
}

#custom-design {
    background: darkslategrey;
}

#custom-design > .switch--slider {
    color: dodgerblue;
    background: darkslateblue;
}

Reactive Attributes

Name	Type	Default	Description
value	bool	False	The value of the switch.

Messages

• Switch.Changed

Bindings

The switch widget defines the following bindings:

Key(s)	Description
enter,space	Toggle the switch state.

Component Classes

The switch widget provides the following component classes:

Class	Description
switch--slider	Targets the slider of the switch.

Additional Notes

• To remove the spacing around a Switch, set border: none; and padding: 0;.

---

textual.widgets.Switch class

def __init__(
    self,
    value=False,
    *,
    animate=True,
    name=None,
    id=None,
    classes=None,
    disabled=False
):

Bases: Widget

A switch widget that represents a boolean value.

Can be toggled by clicking on it or through its bindings.

The switch widget also contains component classes that enable more customization.

Parameters

Parameter	Default	Description
value bool	False	The initial value of the switch.
animate bool	True	True if the switch should animate when toggled.
name str | None	None	The name of the switch.
id str | None	None	The ID of the switch in the DOM.
classes str | None	None	The CSS classes of the switch.
disabled bool	False	Whether the switch is disabled or not.

BINDINGS class-attribute

BINDINGS: list[BindingType] = [
    Binding(
        "enter,space", "toggle_switch", "Toggle", show=False
    )
]

Key(s)	Description
enter,space	Toggle the switch state.

COMPONENT_CLASSES class-attribute

COMPONENT_CLASSES: set[str] = {'switch--slider'}

Class	Description
switch--slider	Targets the slider of the switch.

slider_pos instance-attribute class-attribute

slider_pos = reactive(0.0)

The position of the slider.

value instance-attribute class-attribute

value: reactive[bool] = reactive(False, init=False)

The value of the switch; True for on and False for off.

Changed class

def __init__(self, switch, value):

Bases: Message

Posted when the status of the switch changes.

Can be handled using on_switch_changed in a subclass of Switch or in a parent widget in the DOM.

Attributes

Name	Type	Description
value	bool	The value that the switch was changed to.
switch	Switch	The Switch widget that was changed.

control property

control: Switch

Alias for self.switch.

action_toggle_switch method

def action_toggle_switch(self):

Toggle the state of the switch.

toggle method

def toggle(self):

Toggle the switch value.

As a result of the value changing, a Switch.Changed message will be posted.

Returns

Type	Description
Self	The Switch instance.