Icon button

In plain words

A small button with just a picture (a magnifying glass, a gear) instead of words.

A compact square button that shows a Lucide icon. It is ghost by default, so it fits in toolbars, panel headers and tab bars. tooltip= adds a tooltip on hover.

ui.icon_button · Category: Actions · Full reference →

Preview

Code

pz.row([
    ui.icon_button("search", on_search, tooltip="Search"),
    ui.icon_button("settings", on_settings, tooltip="Settings"),
    ui.icon_button("bell", on_notifications, selected=True),
    ui.icon_button("plus", on_new, variant="filled"),
], spacing=6)

When to use

• For frequent actions whose icon is obvious (search, settings, close, add).
• Always give it a tooltip when the icon alone may be ambiguous.
• selected=True shows a toggled state (a panel that is open, a filter that is on).

Usage

import pyzed as pz
from pyzed import ui

pz.row([
    ui.icon_button("search", on_search, tooltip="Search"),
    ui.icon_button("settings", on_settings, tooltip="Settings"),
    ui.icon_button("bell", on_notifications, selected=True),
    ui.icon_button("plus", on_new, variant="filled"),
], spacing=6)

Variants

About these captures

Each capture is recorded by pyzed itself, off-screen at 2x, in One Dark or One Light to match this site’s theme, and cropped to the component so it shows at its real size. The pointer hovers, presses or types into it; a component that does not react to the pointer cycles through a few themes. With reduced motion you see the first frame. Open Code under a capture to see the snippet that draws it; free names such as on_save stand for your own callbacks.

Size

size="xs"

Code

ui.icon_button("star", on_press, size="xs")

size="sm"

Code

ui.icon_button("star", on_press, size="sm")

size="md"

Code

ui.icon_button("star", on_press, size="md")

size="lg"

Code

ui.icon_button("star", on_press, size="lg")

Variant

variant="ghost"

Code

ui.icon_button("settings", on_press)

variant="filled"

Code

ui.icon_button("settings", on_press, variant="filled")

variant="outline"

Code

ui.icon_button("settings", on_press, variant="outline")

variant="solid"

Code

ui.icon_button("settings", on_press, variant="solid")

variant="tinted"

Code

ui.icon_button("settings", on_press, variant="tinted")

Color

color="accent"

Code

ui.icon_button("sparkles", on_press, color="accent")

color="success"

Code

ui.icon_button("circle-check", on_press, color="success")

color="warning"

Code

ui.icon_button("triangle-alert", on_press, color="warning")

color="error"

Code

ui.icon_button("trash-2", on_press, color="error", variant="outline")

State

Drawn as the pointer shows it: tooltips only open on hover.

selected=True

Code

ui.icon_button("panel-left", on_press, selected=True)

disabled=True

Code

ui.icon_button("lock", on_press, disabled=True)

tooltip="Search"

Code

ui.icon_button("search", on_press, tooltip="Search")

States and events

indicator="accent"

Code

ui.icon_button("bell", on_press, indicator="accent")

tint="error"

Code

ui.icon_button("trash-2", on_press, tint="error")

loading=True

Code

ui.icon_button("refresh-cw", on_press, loading=True)

keys=

Code

ui.icon_button("search", on_press, tooltip="Search", keys="ctrl-f")

Events

Icon 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	Handler gets	When
on_press	()	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.

Imperative

class Toolbar(pz.App):
    def __init__(self):
        self.bold = False

    def toggle_bold(self):
        self.bold = not self.bold

    def view(self):
        return pz.row([
            ui.icon_button("bold", self.toggle_bold, selected=self.bold, tooltip="Bold", keys="ctrl-b"),
            ui.icon_button("trash-2", self.clear, tooltip="Clear", disabled=not self.bold),
        ], spacing=4)

    def clear(self):
        self.bold = False

Declarative

from dataclasses import dataclass


@dataclass
class ToggleBold:
    pass


class Toolbar(pz.App):
    bold = False

    def update(self, message):
        if isinstance(message, ToggleBold):
            self.bold = not self.bold

    def view(self):
        return ui.icon_button("bold", ToggleBold(), selected=self.bold, tooltip="Bold")

Functional

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    bold: bool = False


def view(state, set_state):
    return ui.icon_button("bold", lambda: set_state(bold=not state.bold),
                          selected=state.bold, tooltip="Bold")

Tips

Tip

Run pyzed icons to search the icon names.

Properties and API

ui.icon_button

icon_button(
    name,
    on_press=None,
    *,
    size='md',
    variant='ghost',
    color=None,
    selected=False,
    disabled=False,
    tooltip=None,
    keys=None,
    tint=None,
    loading=False,
    indicator=None,
    theme=None,
)

A square button with just an icon.

Property	Default	Description
name	required	Icon name.
size	"md"	"xs", "sm", "md" or "lg".
variant	"ghost"	As in ui.button. Defaults to "ghost".
color	None	Icon color.
selected	False	Marks it as selected.
disabled	False	Disables it (ignores clicks).
tooltip	None	Tooltip text.
keys	None	Key binding shown in the tooltip.
tint	None	Colors it ("error", "accent"…).
loading	False	Swaps the icon for a spinner and ignores presses.
indicator	None	Adds a small dot in this color at the top right (unread, changes…).
theme	None	Theme to use instead of the current one (pyzed.theme.current()).

Events: on_press (events).

Full reference →

Related

ButtonThe themed button: variants, sizes, icons and shortcuts.

TooltipA hint shown on hover, optionally with its shortcut.

ToolbarThe bar under the tabs: breadcrumbs and buffer actions.