Button

Displays a themed button. It reads its colors from the current theme, can carry an icon and a keyboard shortcut, and comes in several variants and sizes. Any style parameter of pz.button (bg, hover_bg, color, shadow, radius…) overrides the theme’s.

ui.button · Category: Actions · Full reference →

Preview
Code

pz.row([
    ui.button("Cancel", on_cancel, variant="ghost"),
    ui.button("Save", on_save, icon="save", variant="solid", keys="ctrl-s"),
], spacing=8)

Hover and press states with a real pointer.

When to use

For the main actions of a form, dialog or toolbar.
Use variant="solid" for the one primary action and "ghost" for secondary ones.
For a button with only an icon, use Icon button.

Usage

import pyzed as pz
from pyzed import ui

class Editor(pz.App):
    def save(self):
        ...

    def view(self):
        return ui.button("Save", self.save, icon="save", keys="ctrl-s")

Variants

Variant

filled is the default; use solid for the one main action of a screen.

Button: variant="ghost" — `variant="ghost"`

Button: variant="subtle" — `variant="subtle"`

Button: variant="outline" — `variant="outline"`

Button: variant="solid" — `variant="solid"`

Button: variant="tinted" — `variant="tinted"`

Semantic colors

A color name as variant gives a tinted button; tint= colors a solid one.

Button: variant="accent" — `variant="accent"`

Button: variant="success" — `variant="success"`

Button: variant="warning" — `variant="warning"`

Button: variant="error" — `variant="error"`

Button: variant="info" — `variant="info"`

Button: variant="solid", tint="error" — `variant="solid", tint="error"`

Size

size="xs"

Code

ui.button("Extra small", on_press, size="xs")

size="sm"

Code

ui.button("Small", on_press, size="sm")

Content

Button: icon_position="end" — `icon_position="end"`

Button: icon_color="success" — `icon_color="success"`

State

A button without on_press is drawn disabled, so unfinished actions look unfinished.

Button: full_width=True — `full_width=True`

Style overrides

The style arguments of pz.button (bg, hover_bg, pressed_bg, color, border_color, shadow, radius, padding) replace the theme’s values for that button only.

States and events

The pz.* widget underneath: no theme, every color and size is yours.

Examples

Full width

full_width=True stretches the button to its container.

Preview
Code

pz.column([
    ui.button("Sign in", on_press, variant="solid", full_width=True),
    ui.button("Create an account", on_press, variant="outline", full_width=True),
], spacing=8, width=320)

Events

Button has 1 event of its own, listed below. Like every widget it also has the 18 common events (click, double_click, right_click, mouse_enter, drag, key_down, resize…), attached with .on(...): see Events and Events of every component.

Event	Of	Handler gets	When
`on_press`	`ui.button`, `pz.button`	`()`	Message or callable sent on press. `None` disables the control.

Handler gets is what Pyzed passes to your callable: () means nothing. Any handler can also be a message (a value that is not callable), which goes to update().

Handling the events

The same events written three ways. Imperative: methods of the app change self. Declarative: the handlers produce messages and one update() decides. Functional: a pure function draws an immutable state and asks for changes with set_state(...). See Imperative, declarative and functional.

class Editor(pz.App):
    def __init__(self):
        self.saved = 0

    def save(self):                      # on_press: called with nothing
        self.saved += 1

    def view(self):
        return pz.row([
            ui.button("Save", self.save, icon="save", variant="solid", keys="ctrl-s"),
            ui.button("Reset", lambda: setattr(self, "saved", 0), variant="ghost"),
            ui.label(f"Saved {self.saved} times"),
        ], spacing=8, align="center")

class Editor(pz.App):
    saved = 0

    def update(self, message):           # every button sends a message here
        match message:
            case "save":
                self.saved += 1
            case "reset":
                self.saved = 0

    def view(self):
        return pz.row([
            ui.button("Save", "save", icon="save", variant="solid", keys="ctrl-s"),
            ui.button("Reset", "reset", variant="ghost"),
            ui.label(f"Saved {self.saved} times"),
        ], spacing=8, align="center")

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    saved: int = 0


def view(state, set_state):              # a pure function: state in, widgets out
    return pz.row([
        ui.button("Save", lambda: set_state(saved=state.saved + 1), icon="save", variant="solid"),
        ui.button("Reset", lambda: set_state(saved=0), variant="ghost"),
        ui.label(f"Saved {state.saved} times"),
    ], spacing=8, align="center")

Tips

Properties and API

`ui.button`

button(
    content=None,
    on_press=None,
    *,
    icon=None,
    icon_position='start',
    icon_color=None,
    variant='filled',
    tint=None,
    size='md',
    selected=False,
    disabled=False,
    full_width=False,
    keys=None,
    loading=False,
    tooltip=None,
    theme=None,
    **style,
)

A themed button with variants, sizes, an icon and a shortcut.

Property	Default	Description
`content`	`None`	Text or widget.
`icon`	`None`	Name of a Lucide icon (`pyzed icons` lists them).
`icon_position`	`"start"`	`"start"` or `"end"`.
`icon_color`	`None`	Icon color: a theme token or a hex color.
`variant`	`"filled"`	`"filled"`, `"ghost"`, `"subtle"`, `"outline"`, `"solid"`, `"tinted"`, or a semantic color: `"accent"`, `"error"`, `"warning"`, `"success"`, `"info"`.
`tint`	`None`	Color for the `solid` and `tinted` variants.
`size`	`"md"`	`"xs"`, `"sm"`, `"md"` or `"lg"`.
`selected`	`False`	Marks it as selected.
`disabled`	`False`	Disables it (ignores clicks).
`full_width`	`False`	Fills the full width.
`keys`	`None`	Shortcut shown at the end, written as a string: `"ctrl-s"`, `"cmd-k cmd-s"`.
`loading`	`False`	Shows a spinner in place of the icon and ignores presses (keep a `pz.every(1/30, ...)` subscription while it spins).
`tooltip`	`None`	Text shown on hover.
`theme`	`None`	Theme to use instead of the current one (`pyzed.theme.current()`).
`**style`	—	Any `pyzed.button` style parameter (`bg`, `hover_bg`, `color`…).

Events: on_press (events).

Full reference →

`pz.button`

button(
    content,
    on_press=None,
    *,
    padding=None,
    width=None,
    height=None,
    bg=None,
    color=None,
    border_color=None,
    border_width=0.0,
    radius=None,
    shadow=None,
    hover_bg=None,
    hover_color=None,
    hover_border_color=None,
    pressed_bg=None,
    disabled_color=None,
    clip=False,
)

A button with no predefined style. For the themed button use ui.button.

Property	Default	Description
`content`	required	Button content.
`padding`	`None`	Inner padding: `8`, `(vertical, horizontal)` or `(top, right, bottom, left)`.
`width`	`None`	Width: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion).
`height`	`None`	Height: pixels, `"fill"`, `"shrink"` or `"fill:N"` (proportion).
`bg`	`None`	Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`).
`color`	`None`	Text or icon color.
`border_color`	`None`	Border color.
`border_width`	`0.0`	Border width in pixels.
`radius`	`None`	Corner radius: a number or `(top_left, top_right, bottom_right, bottom_left)`.
`shadow`	`None`	Shadow: `(color, (dx, dy), blur)`.
`hover_bg`	`None`	Background on hover.
`hover_color`	`None`	Text color on hover.
`hover_border_color`	`None`	Border color on hover.
`pressed_bg`	`None`	Background while pressed.
`disabled_color`	`None`	Text color when disabled.
`clip`	`False`	Clips content that overflows the bounds.