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;.

---

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:

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

BINDINGS class-attribute

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

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

COMPONENT_CLASSES class-attribute

COMPONENT_CLASSES = {'switch--slider'}

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

slider_pos class-attribute instance-attribute

slider_pos = reactive(0.0)

The position of the slider.

value class-attribute instance-attribute

value = reactive(False, init=False)

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

Changed

Changed(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

Alias for self.switch.

action_toggle_switch

action_toggle_switch()

Toggle the state of the switch.

toggle

toggle()

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.