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.

Outputbutton.pybutton.tcss

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¶

Button.Pressed

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

Bases: Widget

A simple clickable button.

Clicking the button will send a Button.Pressed message, unless the action parameter is provided.

Parameters:

Name	Type	Description	Default
`label` ¶	`TextType \| None`	The text that appears within the button.	`None`
`variant` ¶	`ButtonVariant`	The variant of the button.	`'default'`
`name` ¶	`str \| None`	The name of the button.	`None`
`id` ¶	`str \| None`	The ID of the button in the DOM.	`None`
`classes` ¶	`str \| None`	The CSS classes of the button.	`None`
`disabled` ¶	`bool`	Whether the button is disabled or not.	`False`
`tooltip` ¶	`RenderableType \| None`	Optional tooltip.	`None`
`action` ¶	`str \| None`	Optional action to run when clicked.	`None`

active_effect_duration `instance-attribute` ¶

active_effect_duration = 0.2

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

label `class-attribute` `instance-attribute` ¶

label = label

The text label that appears within the button.

variant `class-attribute` `instance-attribute` ¶

variant = variant

The variant name for the button.

Pressed ¶

Pressed(button)

Bases: Message

Event sent when a Button is pressed and there is no Button action.

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

The button that was pressed.

control `property` ¶

control

An alias for Pressed.button.

This will be the same value as Pressed.button.

action_press ¶

action_press()

Activate a press of the button.

error `classmethod` ¶

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

Utility constructor for creating an error Button variant.

Parameters:

Name	Type	Description	Default
`label` ¶	`TextType \| None`	The text that appears within the button.	`None`
`disabled` ¶	`bool`	Whether the button is disabled or not.	`False`
`name` ¶	`str \| None`	The name of the button.	`None`
`id` ¶	`str \| None`	The ID of the button in the DOM.	`None`
`classes` ¶	`str \| None`	The CSS classes of the button.	`None`
`disabled` ¶	`bool`	Whether the button is disabled or not.	`False`

Returns:

Type	Description
`Button`	A `Button` widget of the 'error' variant.

press ¶

press()

Animate the button and send the Pressed message.

Can be used to simulate the button being pressed by a user.

Returns:

Type	Description
`Self`	The button instance.

success `classmethod` ¶

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

Utility constructor for creating a success Button variant.

Parameters:

Name	Type	Description	Default
`label` ¶	`TextType \| None`	The text that appears within the button.	`None`
`disabled` ¶	`bool`	Whether the button is disabled or not.	`False`
`name` ¶	`str \| None`	The name of the button.	`None`
`id` ¶	`str \| None`	The ID of the button in the DOM.	`None`
`classes` ¶	`str \| None`	The CSS classes of the button.	`None`
`disabled` ¶	`bool`	Whether the button is disabled or not.	`False`

Returns:

Type	Description
`Button`	A `Button` widget of the 'success' variant.

validate_label ¶

validate_label(label)

Parse markup for self.label

warning `classmethod` ¶

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

Utility constructor for creating a warning Button variant.

Parameters:

Name	Type	Description	Default
`label` ¶	`TextType \| None`	The text that appears within the button.	`None`
`disabled` ¶	`bool`	Whether the button is disabled or not.	`False`
`name` ¶	`str \| None`	The name of the button.	`None`
`id` ¶	`str \| None`	The ID of the button in the DOM.	`None`
`classes` ¶	`str \| None`	The CSS classes of the button.	`None`
`disabled` ¶	`bool`	Whether the button is disabled or not.	`False`

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.

Button¶

Example¶

Reactive Attributes¶

Messages¶

Bindings¶

Component Classes¶

Additional Notes¶

label ¶

variant ¶

name ¶

id ¶

classes ¶

disabled ¶

tooltip ¶

action ¶

active_effect_duration instance-attribute ¶

label class-attribute instance-attribute ¶

variant class-attribute instance-attribute ¶

Pressed ¶

button instance-attribute ¶

control property ¶

action_press ¶

error classmethod ¶

label ¶

disabled ¶

name ¶

id ¶

classes ¶

disabled ¶

press ¶

success classmethod ¶

label ¶

disabled ¶

name ¶

id ¶

classes ¶

disabled ¶

validate_label ¶

warning classmethod ¶

label ¶

disabled ¶

name ¶

id ¶

classes ¶

disabled ¶

textual.widgets.button ¶

ButtonVariant module-attribute ¶

`label` ¶

`variant` ¶

`name` ¶

`id` ¶

`classes` ¶

`disabled` ¶

`tooltip` ¶

`action` ¶

active_effect_duration `instance-attribute` ¶

label `class-attribute` `instance-attribute` ¶

variant `class-attribute` `instance-attribute` ¶

button `instance-attribute` ¶

control `property` ¶

error `classmethod` ¶

`label` ¶

`disabled` ¶

`name` ¶

`id` ¶

`classes` ¶

`disabled` ¶

success `classmethod` ¶

`label` ¶

`disabled` ¶

`name` ¶

`id` ¶

`classes` ¶

`disabled` ¶

warning `classmethod` ¶

`label` ¶

`disabled` ¶

`name` ¶

`id` ¶

`classes` ¶

`disabled` ¶

ButtonVariant `module-attribute` ¶