docs/widgets/Button

docs/examples/widgets/button.css

@@ -0,0 +1,3 @@
+Button {
+    margin: 1 2;
+}

docs/examples/widgets/button.py

@@ -0,0 +1,20 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Button
+
+
+class ButtonsApp(App):
+    def compose(self) -> ComposeResult:
+        yield Button("Default", id="foo")
+        yield Button("Disabled", disabled=True)
+        yield Button.success("Success!")
+        yield Button.warning("Warning!")
+        yield Button.error("Error!")
+
+    def on_button_pressed(self, _event: Button.Pressed) -> None:
+        self.app.bell()
+
+
+app = ButtonsApp(css_path="button.css")
+
+if __name__ == "__main__":
+    result = app.run()

docs/widgets/button.md

@@ -1 +1,58 @@
 # Button
+
+## Description
+
+A simple button widget which can be pressed using a mouse click or by pressing ++return++
+when it has focus.
+
+- [x] Focusable
+- [ ] Container
+
+## Example
+
+Clicking any of the buttons in the example app below will result in a ring of the terminal bell.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/button.py"}
+    ```
+
+=== "button.py"
+
+    ```python
+    --8<-- "docs/examples/widgets/button.py"
+    ```
+
+=== "button.css"
+
+    ```css
+    --8<-- "docs/examples/widgets/button.css"
+    ```
+
+## Reactive Attributes
+
+| Name       | Type   | Default     | Description                                                                                                            |
+|------------|--------|-------------|------------------------------------------------------------------------------------------------------------------------|
+| `label`    | `str`  | `""`        | The text that appears inside the button.                                                                               |
+| `variant`  | `str`  | `"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 clicked, and are styled in a way that suggests this. |
+
+## Events
+
+### Pressed
+
+The `Button.Pressed` event is sent when the button is pressed.
+
+- [x] Bubbles
+
+#### Attributes
+
+_No other attributes_
+
+## Additional Notes
+
+* The spacing between the text and the edges of a button are due to border, _not_ padding. To create a button with zero visible padding, use the `border: none;` declaration.
+
+## See Also
+
+* [Button](../reference/button.md) code reference