Badge

In plain words

A tiny colored pill with a word or two, like “beta” or “3 errors”.

A small pill with text and an optional icon. tint picks a semantic color and variant is "soft" (default), "solid" or "outline".

ui.badge · Category: Display · Full reference →

Preview

Code

pz.row([
    ui.badge("accent"),
    ui.badge("success", tint="success"),
    ui.badge("warning", tint="warning"),
    ui.badge("error", tint="error", icon="circle-x"),
], spacing=8)

When to use

• For short read-only statuses: beta, M (modified), v0.4, 3 errors.
• For a round number on top of an icon use Count badge.

Usage

import pyzed as pz
from pyzed import ui

pz.row([
    ui.badge("accent"),
    ui.badge("success", tint="success"),
    ui.badge("warning", tint="warning"),
    ui.badge("error", tint="error", icon="circle-x"),
], spacing=8)

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.

Tint

tint="accent"

Code

ui.badge("accent")

tint="success"

Code

ui.badge("passed", tint="success")

tint="warning"

Code

ui.badge("pending", tint="warning")

tint="error"

Code

ui.badge("failed", tint="error")

tint="info"

Code

ui.badge("info", tint="info")

tint="#c678dd"

Code

ui.badge("custom", tint="#c678dd")

Variant

variant="soft"

Code

ui.badge("soft")

variant="solid"

Code

ui.badge("solid", variant="solid")

variant="outline"

Code

ui.badge("outline", variant="outline")

With an icon

icon="sparkles"

Code

ui.badge("new", icon="sparkles")

icon="circle-x"

Code

ui.badge("3 errors", tint="error", icon="circle-x")

variant="solid", icon=

Code

ui.badge("verified", tint="success", variant="solid", icon="check")

States and events

size="sm"

Code

ui.badge("beta", size="sm")

size="lg"

Code

ui.badge("Pro", size="lg", icon="star")

on_press=

Code

ui.badge("3 issues", tint="warning", on_press=on_press)

Events

Badge 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	()	Makes it clickable.

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 Inbox(pz.App):
    def __init__(self):
        self.unread = 3

    def view(self):
        return ui.badge(f"{self.unread} new", tint="accent",
                        on_press=lambda: setattr(self, "unread", 0))   # on_press makes it clickable

Declarative

class Inbox(pz.App):
    unread = 3

    def update(self, message):
        if message == "read all":
            self.unread = 0

    def view(self):
        return ui.badge(f"{self.unread} new", on_press="read all")

Functional

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    unread: int = 3


def view(state, set_state):
    return ui.badge(f"{state.unread} new", on_press=lambda: set_state(unread=0))

Properties and API

ui.badge

badge(
    content,
    *,
    tint='accent',
    variant='soft',
    icon=None,
    size='md',
    on_press=None,
    theme=None,
)

A small pill for statuses and counters.

Property	Default	Description
content	required	Content: a Widget, a string or a number (converted to text).
tint	"accent"	Semantic color: "accent", "error", "warning", "success", "info" or a token.
variant	"soft"	"soft", "solid" or "outline".
icon	None	Name of a Lucide icon (pyzed icons lists them).
size	"md"	"sm", "md" or "lg".
theme	None	Theme to use instead of the current one (pyzed.theme.current()).

Events: on_press (events).

Full reference →

Related

Count badgeA round counter that shows 99+ above its max.

IndicatorA colored dot for status, presence or unsaved changes.

ChipA compact tag: clickable as a filter, removable with an ✕.