Skip to content

Switch

A simple switch widget which stores a boolean value.

  • Focusable
  • Container

Example

The example below shows switches in various states.

SwitchApp Example switches ▔▔▔▔▔▔▔▔ off:      ▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔ on:       ▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔ focused:  ▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔ custom:   ▁▁▁▁▁▁▁▁

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

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

BINDINGS class-attribute

BINDINGS: list[BindingType] = [
    Binding("enter,space", "toggle", "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 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 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 method

def action_toggle(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.