Stat

In plain words

A big number with its name and whether it went up or down, like on a dashboard.

A dashboard tile: a title, a large value, an optional change (delta, shown as +4.2% in green or red) and an optional trend drawn as a sparkline.

ui.stat · Category: Data · Full reference →

Preview

Code

pz.row([
    ui.stat("Users", "1,284", delta=12.5, trend=[3, 5, 4, 6, 8, 7, 9], width=200),
    ui.stat("Errors", "37", delta=-8.0, width=200),
    ui.stat("Build time", "1m 12s", width=200),
], spacing=12)

When to use

• For key numbers at the top of a dashboard or report.

Usage

import pyzed as pz
from pyzed import ui

pz.row([
    ui.stat("Users", "1,284", delta=12.5, trend=[3, 5, 4, 6, 8, 7, 9], width=200),
    ui.stat("Errors", "37", delta=-8.0, width=200),
    ui.stat("Build time", "1m 12s", width=200),
], spacing=12)

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.

Content

Value only

Code

ui.stat("Build time", "1m 12s", width=190)

delta=12.5

Code

ui.stat("Users", "1,284", delta=12.5, width=190)

delta=-8.0

Code

ui.stat("Errors", "37", delta=-8.0, width=190)

trend=[...]

Code

ui.stat("Revenue", "$9.4k", delta=4.2, trend=[3, 5, 4, 6, 8, 7, 9], width=190)

States and events

With inverse=True a drop is good news (green), for errors or latency.

icon=, inverse=True

Code

ui.stat("Errors", "12", delta=-8.0, inverse=True, icon="bug", width=180)

on_press=

Code

ui.stat("Users", "1,204", delta=4.2, icon="users", on_press=on_press, width=180)

Events

Stat 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 the card 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 Dashboard(pz.App):
    def __init__(self):
        self.detail = None

    def view(self):
        return pz.column([
            pz.row([ui.stat("Users", "1,284", delta=12.5, width=200,
                            on_press=lambda: setattr(self, "detail", "Users")),   # the whole card
                    ui.stat("Errors", "37", delta=-8.0, width=200,
                            on_press=lambda: setattr(self, "detail", "Errors"))], spacing=12),
            ui.muted(f"Details of {self.detail}" if self.detail else "Click a number"),
        ], spacing=8)

Declarative

from dataclasses import dataclass


@dataclass
class Open:
    metric: str


class Dashboard(pz.App):
    detail = None

    def update(self, message):
        match message:
            case Open(metric):
                self.detail = metric

    def view(self):
        return pz.row([ui.stat(m, v, width=200, on_press=Open(m))
                       for m, v in (("Users", "1,284"), ("Errors", "37"))], spacing=12)

Functional

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    detail: str = ""


def view(state, set_state):
    return pz.row([ui.stat(m, v, width=200, on_press=lambda m=m: set_state(detail=m))
                   for m, v in (("Users", "1,284"), ("Errors", "37"))], spacing=12)

Properties and API

ui.stat

stat(
    title,
    value,
    *,
    delta=None,
    trend=None,
    width=None,
    icon=None,
    inverse=False,
    on_press=None,
    theme=None,
)

A dashboard number: title, large value, optional change (+4.2%) and sparkline.

Property	Default	Description
title	required	Title.
value	required	Current value.
delta	None	Change in %; green if positive, red otherwise.
trend	None	Values for the sparkline.
width	None	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
icon	None	Icon before the title.
inverse	False	Colors a drop green and a rise red (errors, latency…).
theme	None	Theme to use instead of the current one (pyzed.theme.current()).

Events: on_press (events).

Full reference →

Related

SparklineA tiny line chart for trends.

Bar chartA vertical bar chart with labels.

DonutA donut chart with a label in the middle.