Skip to content

Button

A simple button widget which can be pressed using a mouse click or by pressing Enter when it has focus.

  • Focusable
  • Container

Example

The example below shows each button variant, and its disabled equivalent. Clicking any of the non-disabled buttons in the example app below will result in the app exiting and the details of the selected button being printed to the console.

ButtonsApp Standard ButtonsDisabled Buttons ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ DefaultDefault ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ Primary!Primary! ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ Success!Success! ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ Warning!Warning! ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁ ▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ Error!Error! ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁

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


class ButtonsApp(App[str]):
    CSS_PATH = "button.tcss"

    def compose(self) -> ComposeResult:
        yield Horizontal(
            VerticalScroll(
                Static("Standard Buttons", classes="header"),
                Button("Default"),
                Button("Primary!", variant="primary"),
                Button.success("Success!"),
                Button.warning("Warning!"),
                Button.error("Error!"),
            ),
            VerticalScroll(
                Static("Disabled Buttons", classes="header"),
                Button("Default", disabled=True),
                Button("Primary!", variant="primary", disabled=True),
                Button.success("Success!", disabled=True),
                Button.warning("Warning!", disabled=True),
                Button.error("Error!", disabled=True),
            ),
        )

    def on_button_pressed(self, event: Button.Pressed) -> None:
        self.exit(str(event.button))


if __name__ == "__main__":
    app = ButtonsApp()
    print(app.run())
Button {
    margin: 1 2;
}

Horizontal > VerticalScroll {
    width: 24;
}

.header {
    margin: 1 0 0 2;
    text-style: bold;
}

Reactive Attributes

Name Type Default Description
label str "" The text that appears inside the button.
variant ButtonVariant "default" Semantic styling variant. One of default, primary, success, warning, error.
disabled bool False Whether the button is disabled or not. Disabled buttons cannot be focused or clicked, and are styled in a way that suggests this.

Messages

Bindings

This widget has no bindings.

Component Classes

This widget has no component classes.

Additional Notes

  • The spacing between the text and the edges of a button are not due to padding. The default styling for a Button has the height set to 3 lines and a min-width of 16 columns. To create a button with zero visible padding, you will need to change these values and also remove the border with border: none;.

textual.widgets.Button class

def __init__(
    self,
    label=None,
    variant="default",
    *,
    name=None,
    id=None,
    classes=None,
    disabled=False
):

Bases: Widget

A simple clickable button.

Parameters
Parameter Default Description
label
TextType | None
None

The text that appears within the button.

variant
ButtonVariant
'default'

The variant of the button.

name
str | None
None

The name of the button.

id
str | None
None

The ID of the button in the DOM.

classes
str | None
None

The CSS classes of the button.

disabled
bool
False

Whether the button is disabled or not.

active_effect_duration instance-attribute

active_effect_duration = 0.3

Amount of time in seconds the button 'press' animation lasts.

label instance-attribute class-attribute

label: reactive[TextType] = label

The text label that appears within the button.

variant instance-attribute class-attribute

variant = variant

The variant name for the button.

Pressed class

def __init__(self, button):

Bases: Message

Event sent when a Button is pressed.

Can be handled using on_button_pressed in a subclass of Button or in a parent widget in the DOM.

button instance-attribute

button: Button = button

The button that was pressed.

control property

control: Button

An alias for Pressed.button.

This will be the same value as Pressed.button.

action_press method

def action_press(self):

Activate a press of the button.

error classmethod

def error(
    cls,
    label=None,
    *,
    name=None,
    id=None,
    classes=None,
    disabled=False
):

Utility constructor for creating an error Button variant.

Parameters
Parameter Default Description
label
TextType | None
None

The text that appears within the button.

disabled
bool
False

Whether the button is disabled or not.

name
str | None
None

The name of the button.

id
str | None
None

The ID of the button in the DOM.

classes
str | None
None

The CSS classes of the button.

disabled
bool
False

Whether the button is disabled or not.

Returns
Type Description
Button

A Button widget of the 'error' variant.

press method

def press(self):

Respond to a button press.

Parameters
Parameter Default Description
level
required

Minimum level required for the animation to take place (inclusive).

Returns
Type Description
Self

The button instance.

success classmethod

def success(
    cls,
    label=None,
    *,
    name=None,
    id=None,
    classes=None,
    disabled=False
):

Utility constructor for creating a success Button variant.

Parameters
Parameter Default Description
label
TextType | None
None

The text that appears within the button.

disabled
bool
False

Whether the button is disabled or not.

name
str | None
None

The name of the button.

id
str | None
None

The ID of the button in the DOM.

classes
str | None
None

The CSS classes of the button.

disabled
bool
False

Whether the button is disabled or not.

Returns
Type Description
Button

A Button widget of the 'success' variant.

validate_label method

def validate_label(self, label):

Parse markup for self.label

warning classmethod

def warning(
    cls,
    label=None,
    *,
    name=None,
    id=None,
    classes=None,
    disabled=False
):

Utility constructor for creating a warning Button variant.

Parameters
Parameter Default Description
label
TextType | None
None

The text that appears within the button.

disabled
bool
False

Whether the button is disabled or not.

name
str | None
None

The name of the button.

id
str | None
None

The ID of the button in the DOM.

classes
str | None
None

The CSS classes of the button.

disabled
bool
False

Whether the button is disabled or not.

Returns
Type Description
Button

A Button widget of the 'warning' variant.

textual.widgets.button

ButtonVariant module-attribute

ButtonVariant = Literal[
    "default", "primary", "success", "warning", "error"
]

The names of the valid button variants.

These are the variants that can be used with a Button.