Checkbox

Added in version 0.13.0

A simple checkbox widget which stores a boolean value.

• Focusable
• Container

Example

The example below shows check boxes in various states.

Outputcheckbox.pycheckbox.tcss

from textual.app 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__":
    CheckboxApp().run()

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.

Messages

• Checkbox.Changed

Bindings

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.

---

Bases: ToggleButton

A check box widget that represents a boolean value.

Parameters:

Name	Type	Description	Default
label	ContentText	The label for the toggle.	''
value	bool	The initial value of the toggle.	False
button_first	bool	Should the button come before the label, or after?	True
name	str | None	The name of the toggle.	None
id	str | None	The ID of the toggle in the DOM.	None
classes	str | None	The CSS classes of the toggle.	None
disabled	bool	Whether the button is disabled or not.	False
tooltip	RenderableType | None	RenderableType | None = None,	None
compact	bool	Show a compact button.	False

Changed

Changed(toggle_button, value)

Bases: Changed

Posted when the value of the checkbox changes.

This message can be handled using an on_checkbox_changed method.

Parameters:

Name	Type	Description	Default
toggle_button	ToggleButton	The toggle button sending the message.	required
value	bool	The value of the toggle button.	required

checkbox property

checkbox

The checkbox that was changed.

control property

control

An alias for Changed.checkbox.