Skip to content


Added in version 0.13.0

A simple checkbox widget which stores a boolean value.

  • Focusable
  • Container


The example below shows check boxes in various states.

CheckboxApp ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ X Arrakis 😓 ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔▔▔▔▔▔ X Caladan ▁▁▁▁▁▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔▔▔▔▔ X Chusuk ▁▁▁▁▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ XGiedi Prime ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔▔▔▔ XGinaz ▁▁▁▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔▔▔▔▔▔ X Grumman ▁▁▁▁▁▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔▔▔▔▔▔▃▃ XKaitain ▁▁▁▁▁▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔

from import App, ComposeResult
from textual.containers import VerticalScroll
from textual.widgets import Checkbox

class CheckboxApp(App[None]):
    CSS_PATH = "checkbox.tcss"

    def compose(self) -> ComposeResult:
        with VerticalScroll():
            yield Checkbox("Arrakis :sweat:")
            yield Checkbox("Caladan")
            yield Checkbox("Chusuk")
            yield Checkbox("[b]Giedi Prime[/b]")
            yield Checkbox("[magenta]Ginaz[/]")
            yield Checkbox("Grumman", True)
            yield Checkbox("Kaitain", id="initial_focus")
            yield Checkbox("Novebruns", True)

    def on_mount(self):
        self.query_one("#initial_focus", Checkbox).focus()

if __name__ == "__main__":
Screen {
    align: center middle;

VerticalScroll {
    width: auto;
    height: auto;
    background: $boost;
    padding: 2;

Reactive Attributes

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



The checkbox widget defines the following bindings:

Key(s) Description
enter, space Toggle the value.

Component Classes

The checkbox widget inherits the following component classes:

Class Description
toggle--button Targets the toggle button itself.
toggle--label Targets the text label of the toggle button.

textual.widgets.Checkbox class

Bases: ToggleButton

A check box widget that represents a boolean value.

Changed class

Bases: ToggleButton.Changed

Posted when the value of the checkbox changes.

This message can be handled using an on_checkbox_changed method.

checkbox property

checkbox: Checkbox

The checkbox that was changed.

control property

control: Checkbox

An alias for Changed.checkbox.