Core widgets

The core widgets are implemented in Rust and imported from pyzed. They are the building blocks of the components. See the layout guide for sizes, padding and colors.

Widget

Widget

An immutable node of the UI tree, implemented in Rust. Returned by every widget and component function. Wherever a child is expected you can also pass a string or a number (converted to text) or None (ignored).

Every widget has widget.on(...) (see Events) and widget.style(*styles, **props), which styles it like CSS: background, borders, radius, shadow, padding, margin, size and the typography of every text inside. widget.style_props() returns what was set. widget.classes(*names, id=None) applies the matching rules of pz.stylesheet, like HTML’s class and id. See Styles.

widget.animate(*animations, **options) plays presets or keyframe animations (on mount, hover, press, focus, click or while active) and widget.transition(**props) animates property changes like a CSS transition. See Animation.

Layout

column

column(
    children=None,
    *,
    spacing=0.0,
    padding=None,
    width=None,
    height=None,
    align=None,
    max_width=None,
    clip=False,
)

Stacks its children vertically.

Parameter	Description
children	List of children. Nested lists are flattened and None and False are ignored, so you can write cond and widget.
spacing	Space between children, in pixels.
padding	Inner padding: 8, (vertical, horizontal) or (top, right, bottom, left).
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
align	Alignment of the children on the cross axis: "start", "center" or "end".
max_width	Maximum width in pixels.
clip	Clips content that overflows the bounds.

pz.column([pz.text("One"), pz.text("Two")], spacing=8, padding=16)

row

row(
    children=None,
    *,
    spacing=0.0,
    padding=None,
    width=None,
    height=None,
    align=None,
    clip=False,
    wrap=False,
    line_spacing=None,
)

Lays out its children horizontally.

Parameter	Description
children	List of children. Nested lists are flattened and None and False are ignored, so you can write cond and widget.
spacing	Space between children, in pixels.
padding	Inner padding: 8, (vertical, horizontal) or (top, right, bottom, left).
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
align	Alignment of the children on the cross axis: "start", "center" or "end".
clip	Clips content that overflows the bounds.
wrap	Line wrapping / moves children to a new row when they don’t fit.
line_spacing	Space between rows when wrap=True.

pz.row([ui.label("Name"), pz.hspace(), ui.button("OK", "ok")], align="center")

container

container(
    content=None,
    *,
    padding=None,
    width=None,
    height=None,
    max_width=None,
    max_height=None,
    align_x=None,
    align_y=None,
    center=False,
    bg=None,
    color=None,
    border_color=None,
    border_width=0.0,
    radius=None,
    shadow=None,
    clip=False,
    gradient=None,
)

Wraps a child to give it size, alignment, background, border, radius and shadow.

Parameter	Description
content	The child (or None for an empty box, handy as a colored rectangle).
padding	Inner padding: 8, (vertical, horizontal) or (top, right, bottom, left).
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
max_width	Maximum width in pixels.
max_height	Maximum height in pixels.
align_x	Horizontal alignment: "start"/"left", "center", "end"/"right".
align_y	Vertical alignment: "start"/"top", "center", "end"/"bottom".
center	Centers the content on both axes and fills all the space.
bg	Background color ("#rrggbb[aa]", (r, g, b[, a]) or "transparent").
color	Text or icon color.
border_color	Border color.
border_width	Border width in pixels.
radius	Corner radius: a number or (top_left, top_right, bottom_right, bottom_left).
shadow	Shadow: (color, (dx, dy), blur).
clip	Clips content that overflows the bounds.
gradient	Linear background gradient: (angle, [colors]) or (angle, [(position, color), ...]).

center

center(content, **kwargs)

Centers content in all the available space. Equivalent to container(content, center=True).

Parameter	Description
content	Content: a Widget, a string or a number (converted to text).
kwargs	Any container parameter.

scrollable

scrollable(
    content,
    *,
    direction='vertical',
    width=None,
    height=None,
    padding=None,
    id=None,
    anchor_bottom=False,
    rail=None,
    scroller=None,
    scroller_hover=None,
    scrollbar_width=8.0,
    scroller_width=None,
    margin=0.0,
    on_scroll=None,
)

Makes its content scrollable.

Parameter	Description
content	Content: a Widget, a string or a number (converted to text).
direction	"vertical", "horizontal" or "both".
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
padding	Inner padding: 8, (vertical, horizontal) or (top, right, bottom, left).
id	Stable identifier used to focus or scroll it with a Command.
anchor_bottom	Keeps the scroll pinned to the end (logs, terminals, chats).
rail	Scrollbar rail color.
scroller	Scroller color.
scroller_hover	Scroller color on hover.
scrollbar_width	Scrollbar width.
scroller_width	Scroller width (defaults to the scrollbar’s).
margin	Margin between the scrollbar and the content.
on_scroll	Callable that receives a dict with x, y, relative_x, relative_y, width, height, content_width and content_height.

stack

stack(children=None, *, width=None, height=None)

Layers its children on top of each other, the last one on top. The basis for layers, modals and notifications.

Parameter	Description
children	List of children. Nested lists are flattened and None and False are ignored, so you can write cond and widget.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).

space

space(width=None, height=None)

Empty space of a given size.

Parameter	Description
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).

hspace

hspace(width='fill')

Flexible horizontal gap: pushes the siblings in a row towards the edges.

Parameter	Description
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).

vspace

vspace(height='fill')

Flexible vertical gap: pushes the siblings in a column towards the edges.

Parameter	Description
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).

rule

rule(*, vertical=False, thickness=1.0, color=None)

A horizontal (or vertical) divider line.

Parameter	Description
vertical	Vertical line instead of horizontal.
thickness	Thickness in pixels.
color	Text or icon color.

A horizontal rule fills the full width. Inside a column that should shrink, set width="shrink" on the column.

grid

grid(
    children=None,
    *,
    columns=None,
    rows=None,
    max_width=None,
    spacing=0.0,
    row_spacing=None,
    height=None,
    aspect_ratio=None,
    width=None,
    padding=None,
    align_x=None,
    align_y=None,
)

Lays out its children in a grid. With columns=3 the columns are equal (or max_width fits as many as possible). With track lists (columns=[200, "1fr", "auto"], rows=...) it works like a CSS grid: numbers are pixels, "auto" fits the content and "<n>fr" shares the space left. Wrap children in pz.cell to place them and make them span; the rest fill the free cells row by row. See Layout.

Parameter	Description
children	List of children. Nested lists are flattened and None and False are ignored, so you can write cond and widget.
columns	Number of equal columns, or tracks: a list ([200, "1fr", "auto"]) or a string ("200 1fr auto").
rows	Row tracks, like columns. Rows beyond the list are "auto".
max_width	Fits as many columns of at most this width as possible (columns=<int> only).
spacing	Space between cells.
row_spacing	Space between rows, if different.
height	With columns=<int>: height of each row. With tracks: the grid’s height.
aspect_ratio	Keeps cells at this width/height ratio (columns=<int> only).
width	With columns=<int>: pixels. With tracks: the grid’s width (default "fill").
padding	Space around the cells.
align_x	Horizontal alignment of items in their cells: "start", "center", "end".
align_y	Vertical alignment of items in their cells.

pz.grid([pz.cell(header, column=0, row=0, column_span=2), sidebar, content],
        columns=[200, "1fr"], rows=[48, "1fr"], spacing=8, height="fill")

cell

cell(
    content,
    *,
    column=None,
    row=None,
    column_span=1,
    row_span=1,
    align_x=None,
    align_y=None,
)

Places a child in a track grid: its column and row (from 0) and how many it spans. Children without a cell fill the free cells row by row. Outside a grid it is just the child.

Parameter	Description
content	The widget.
column	Column index (from 0).
row	Row index (from 0).
column_span	Columns it covers.
row_span	Rows it covers.
align_x	Horizontal alignment in the cell.
align_y	Vertical alignment in the cell.

pz.cell(ui.button("Save"), column=2, row=3, align_x="end")

box

box(
    *children,
    display='block',
    direction='row',
    gap=0,
    wrap=False,
    justify='start',
    align=None,
    columns=None,
    rows=None,
    overflow='visible',
    class_=None,
    id=None,
    style=None,
    **props,
)

A container for anything, like an HTML div: it lays out its children (display "block", "flex", "grid" or "stack") and takes every style property, stylesheet classes and an id. Children styled with position="absolute" are placed by top/right/bottom/left above the rest. See Boxes.

Parameter	Description
children	The widgets, one by one or in lists. None and False are skipped.
display	"block" (one under another, as wide as the box), "flex", "grid" or "stack".
direction	With display="flex": "row" or "column".
gap	Space between children.
wrap	With "flex" rows: wraps onto new lines.
justify	With "flex": "start", "center", "end", "between", "around" or "evenly".
align	"start", "center", "end" or "stretch" (the default for "block").
columns	With "grid": a count of equal columns or tracks ("200 1fr auto").
rows	With "grid": row tracks.
overflow	"visible", "hidden", "scroll", "scroll_x" or "scroll_y".
class_	Stylesheet classes ("card selected" or a list).
id	The id for #id rules.
style	A pz.Style, dict or style name.
props	Style properties, on top of the rest.

pz.box(title, pz.box(cancel, save, display="flex", justify="end", gap=8), class_="card", gap=12)

flex

flex(
    children=(),
    *,
    direction='row',
    justify='start',
    align='start',
    gap=0,
    wrap=False,
    padding=None,
    width=None,
    height=None,
)

Lays children out along one axis, like CSS flexbox, with justify on the main axis and align on the cross axis. Use pz.flex_item to make a child grow or give it a fixed size.

Parameter	Description
children	The widgets, or pz.flex_item(...) for children with their own sizing.
direction	"row" or "column".
justify	"start", "center", "end", "between", "around" or "evenly". No effect when a child grows.
align	Cross-axis alignment: "start", "center" or "end".
gap	Space between children.
wrap	Wraps onto new lines (rows with justify="start" only).
padding	Space around the children.
width	Width.
height	Height.

pz.flex([logo, title, pz.flex_item(search, grow=1), avatar], justify="between", align="center", gap=8)

flex_item

flex_item(content, *, grow=1, basis=None, align=None)

Sizes a child of pz.flex.

Parameter	Description
content	The widget.
grow	Share of the free space on the main axis (0 keeps its natural size).
basis	A fixed main size in pixels, instead of growing.
align	Cross-axis alignment for this child.

anchor

anchor(
    content,
    *,
    x=0,
    y=0,
    width=100,
    height=28,
    anchor='top_left',
    min_width=0,
    min_height=0,
    max_width=0,
    max_height=0,
    pivot=(0.5, 0.5),
    rotate=0,
)

Places a child of pz.anchor_layout at x, y with width and height (in the layout’s design size) and says how it follows a resize.

Parameter	Description
content	The widget.
x	Left edge in the design size.
y	Top edge in the design size.
width	Width in the design size.
height	Height in the design size.
anchor	A preset of pyzed.anchors.PRESETS ("top_right", "bottom_wide", "center", "full"…), words ("left right bottom") or a tuple of edges.
min_width	Smallest width when it stretches (0: no limit).
min_height	Smallest height when it stretches.
max_width	Largest width when it stretches (0: no limit).
max_height	Largest height when it stretches.
pivot	(x, y) from 0 to 1: the point that stays put when a limit stops it, and that rotate turns around.
rotate	Degrees clockwise.

pz.anchor(ui.button("Close", on_close), x=284, y=252, width=100, height=32, anchor="bottom_right")

anchor_layout

anchor_layout(children, *, design=None, width='fill', height='fill')

Places children made with pz.anchor freely, like a designed form: when it is resized, each child keeps its distance to the edges it is anchored to, stretches between opposite ones and stays centered otherwise. Later children are drawn on top. See Anchored layouts.

Parameter	Description
children	Children made with pz.anchor(...) (None is skipped).
design	(width, height) the children were laid out in; by default the smallest size that holds them.
width	Width.
height	Height.

pz.anchor_layout([
    pz.anchor(ui.heading("Report"), x=16, y=12, width=368, height=28, anchor="top_wide"),
    pz.anchor(ui.button("Close", on_close), x=284, y=252, width=100, height=32, anchor="bottom_right"),
], design=(400, 300))

place

place(
    rect,
    anchor,
    design,
    actual,
    *,
    min_size=(0, 0),
    max_size=(0, 0),
    pivot=(0.5, 0.5),
)

Where a box designed in a parent of size design goes in a parent of size actual, following its anchor, with size limits and a pivot. The math behind pz.anchor_layout and designed forms.

Parameter	Description
rect	(x, y, width, height) in the design size.
anchor	A preset, words or edges.
design	The parent’s design size.
actual	The parent’s current size.
min_size	(width, height) lower limits (0: none).
max_size	(width, height) upper limits (0: none).
pivot	The point that stays put when a limit stops the box from stretching.

anchors.place((20, 20, 100, 30), "top_right", design=(400, 300), actual=(600, 300))  # (220, 20, 100, 30)

PRESETS

The 16 anchor presets by name (top_left, top_center, top_right, top_wide, center_left, center, center_right, center_wide, bottom_left, bottom_center, bottom_right, bottom_wide, left_tall, center_tall, right_tall, full), each the tuple of edges it anchors to.

edges

edges(anchor)

The edges of an anchor given as a preset name, words or edges. Raises ValueError for anything else.

Parameter	Description
anchor	What to read.

preset_of

preset_of(edges)

The name of the preset a set of edges matches (every set is one of the 16).

Parameter	Description
edges	Edges.

preset

preset(horizontal, vertical)

The preset placed horizontal (left, center, right, wide) and vertical (top, center, bottom, tall).

Parameter	Description
horizontal	Placement on the x axis.
vertical	Placement on the y axis.

axes

axes(edges)

The (horizontal, vertical) placement of a set of edges, such as ("right", "top").

Parameter	Description
edges	Edges.

snap_to

snap_to(anchor, rect, parent, margin=0.0)

A box moved (and sized, on stretched axes) to sit where an anchor points: against the anchored edges, centered or filling the parent, margin pixels in.

Parameter	Description
anchor	A preset, words or edges.
rect	The box.
parent	The parent’s size.
margin	Distance to the edges.

offsets

offsets(rect, parent)

The distances (left, top, right, bottom) from each side of the parent to a box.

Parameter	Description
rect	The box.
parent	The parent’s size.

pivot_offset

pivot_offset(size, pivot, rotate=0.0, scale=1.0)

The translation that makes a rotation and a scale (which turn around a box’s center) turn around pivot instead.

Parameter	Description
size	The box’s size.
pivot	(x, y) from 0 to 1.
rotate	Degrees clockwise.
scale	Scale factor.

focusable

focusable(
    content,
    on_key=None,
    *,
    keys=None,
    id=None,
    ring_color=None,
    ring_radius=4.0,
    ring_offset=2.0,
)

Lets any widget take the keyboard focus like a text field: a click or Tab focuses it (Command.focus(id) too) and, while it has it, the combos in keys call on_key(combo) instead of reaching the app’s on_key. A ring is drawn around it once the keyboard is used on it. The library’s switches, check boxes, sliders, segmented controls and radio groups use it.

Parameter	Description
content	The control.
on_key	Called with the combo ("space", "shift-right"…) of each key in keys pressed while it has the focus. None leaves content unfocusable.
keys	The combos it takes (by default Space, Enter, the arrows, Home and End); "*" takes every key. Tab is left to move the focus.
id	Stable identifier used to focus or scroll it with a Command.
ring_color	Color of the focus ring (none by default).
ring_radius	Corner radius of the ring.
ring_offset	Pixels between the control and the ring.

pz.focusable(stars, lambda combo: self.rate(+1 if combo == "right" else -1), keys=["left", "right"], ring_color="#528bff")

window_edges

window_edges(content, *, border=6.0, enabled=True)

Wraps the whole view of a window without system decorations so that pressing near its edges resizes the window (the corners take twice as much room). ui.window_frame already uses it.

Parameter	Description
content	The window’s whole view.
border	Width in pixels of the area that resizes.
enabled	False turns it off (for a maximized window).

pz.window_edges(view, enabled=not self.window_maximized)

resizable

resizable(
    content,
    *,
    edge='right',
    size=240.0,
    min_size=80.0,
    max_size=None,
    on_resize=None,
    color=None,
    hover_color=None,
    thickness=1.0,
    handle=8.0,
    width=None,
    height=None,
)

A panel whose edge can be dragged to resize it. It keeps the size the user drags it to; on_resize(size) is called when a drag ends so you can save it. Changing size later resets it.

Parameter	Description
content	The panel’s content.
edge	The edge with the handle: "right" (a left sidebar), "left", "top" (a bottom panel) or "bottom".
size	Starting width (height for top/bottom edges).
min_size	Smallest size.
max_size	Largest size.
on_resize	Called with the new size when a drag ends.
color	Line color.
hover_color	Line color while hovered or dragged.
thickness	Line thickness.
handle	Width of the area that can be grabbed.
width	Width for top/bottom edges.
height	Height for left/right edges.

pz.row([pz.resizable(sidebar, edge="right", size=240, on_resize=self.save_width), editor])

split

split(
    first,
    second,
    *,
    ratio=0.5,
    on_resize=None,
    vertical=False,
    min_size=80.0,
    min_size_second=None,
    color=None,
    hover_color=None,
    thickness=1.0,
    handle=8.0,
    width=None,
    height=None,
)

Two panes with a draggable divider. For the theme style use ui.split.

Parameter	Description
first	First pane.
second	Second pane.
ratio	Proportion of the first pane (0–1). The split keeps the ratio the user drags to until this changes.
on_resize	Callable that receives the new ratio while dragging.
vertical	Stacks the panes top/bottom.
min_size	Minimum size of the first pane.
min_size_second	Minimum size of the second pane.
color	Divider color.
hover_color	Divider color on hover or while dragging.
thickness	Line thickness.
handle	Width of the draggable area.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).

pin

pin(content, *, x=0.0, y=0.0, width=None, height=None)

Places content at (x, y) inside a box. Use it in a stack to position popovers and context menus.

Parameter	Description
content	Content: a Widget, a string or a number (converted to text).
x	Horizontal position.
y	Vertical position.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).

responsive

responsive(function)

Builds its content with function(width, height) using the space actually available, so the layout can adapt (for example, hiding a sidebar when the window is narrow).

Parameter	Description
function	Function that receives (width, height) and returns a widget.

FlexItem

class FlexItem

A child of pz.flex with its own sizing; made with pz.flex_item.

Text and icons

text

text(
    content,
    *,
    size=None,
    color=None,
    font=None,
    weight=None,
    italic=False,
    line_height=None,
    align_x=None,
    align_y=None,
    width=None,
    height=None,
    wrap=True,
    selectable=None,
    selection_color=None,
)

A piece of text.

Parameter	Description
content	Content: a Widget, a string or a number (converted to text).
size	Font size.
color	Text or icon color.
font	"sans" (IBM Plex Sans), "mono", "icons", "serif" or the name of a family loaded with load_font.
weight	"thin", "light", "normal", "medium", "semibold", "bold", "black" or a number (100–900).
italic	Italic.
line_height	Line height relative to the size (1.0, 1.5…).
align_x	Horizontal alignment: "start"/"left", "center", "end"/"right".
align_y	Vertical alignment: "start"/"top", "center", "end"/"bottom".
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
wrap	Line wrapping. With False the text doesn’t wrap.
selectable	True lets the mouse select the text (drag, double-click a word, triple-click a block) and Ctrl+C copy it. A string names a selection group: the texts and Markdown of one group form a single selection, in the order they are drawn (the lines of a log, the messages of a chat).
selection_color	Color behind the selected text.

icon

icon(name, *, size=16, color=None)

A Lucide icon. color defaults to the surrounding text color.

Parameter	Description
name	Icon name (pyzed icons lists them).
size	Size in pixels.
color	Color.

pz.icon("folder", size=16, color="#74ade8")

svg

svg(
    source,
    *,
    width=None,
    height=None,
    color=None,
    content_fit=None,
    opacity=1.0,
    rotation=0.0,
)

An SVG image.

Parameter	Description
source	Path to an .svg, the SVG code as a string (starting with <) or bytes.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
color	If given, tints the whole SVG with that color (useful for monochrome icons).
content_fit	"contain", "cover", "fill", "none" or "scale-down".
opacity	Opacity from 0 to 1.
rotation	Rotation in degrees.

Images and content

image

image(
    source,
    *,
    width=None,
    height=None,
    content_fit=None,
    filter='linear',
    opacity=1.0,
    radius=0.0,
    rotation=0.0,
    scale=1.0,
    size=None,
)

A bitmap image (PNG, JPEG, GIF, BMP, WebP…) from a path or bytes, or raw RGBA pixels.

Parameter	Description
source	File path, bytes of the encoded file, or raw RGBA pixels with size=(width, height).
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
content_fit	"contain", "cover", "fill", "none" or "scale-down".
filter	"linear" (smooth) or "nearest" (crisp pixels, for pixel art).
opacity	Opacity from 0 to 1.
radius	Corner radius.
rotation	Rotation in degrees.
scale	Scale.
size	(width, height) when source is raw RGBA pixels.

pz.image("photo.jpg", width=320, content_fit="cover", radius=8)

image_viewer

image_viewer(
    source,
    *,
    width=None,
    height=None,
    min_scale=0.25,
    max_scale=10.0,
    scale_step=0.1,
    filter='linear',
    size=None,
)

An image you can pan (by dragging) and zoom (mouse wheel), like Iced’s viewer.

Parameter	Description
source	File path, bytes of the encoded file, or raw RGBA pixels with size=(width, height).
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
min_scale	Minimum zoom.
max_scale	Maximum zoom.
scale_step	How much the zoom changes per wheel step.
filter	"linear" (smooth) or "nearest" (crisp pixels, for pixel art).
size	(width, height) for raw RGBA pixels.

markdown

markdown(
    source,
    *,
    size=14.0,
    color=None,
    link_color=None,
    code_color=None,
    code_bg=None,
    on_link=None,
    width=None,
    selectable=None,
    selection_color=None,
)

Renders Markdown (headings, lists, code blocks, quotes, tables, links…). For the theme colors use ui.markdown.

Parameter	Description
source	The Markdown text.
size	Size.
color	Text or icon color.
link_color	Link color.
code_color	Code color.
code_bg	Code background.
on_link	Callable that receives the URL when a link is clicked.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
selectable	True lets the mouse select the text (drag, double-click a word, triple-click a block) and Ctrl+C copy it. A string names a selection group: the texts and Markdown of one group form a single selection, in the order they are drawn (the lines of a log, the messages of a chat).
selection_color	Color behind the selected text.

rich_text

rich_text(
    spans,
    *,
    size=None,
    color=None,
    font=None,
    line_height=None,
    width=None,
    align_x=None,
    wrap=True,
)

Text made of spans with different styles. Plain strings are unstyled spans.

Parameter	Description
spans	List of span(...) or strings.
size	Size.
color	Text or icon color.
font	Font of the span or text (family name, e.g. "IBM Plex Mono").
line_height	Line height.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
align_x	Horizontal alignment: "start"/"left", "center", "end"/"right".
wrap	Line wrapping / moves children to a new row when they don’t fit.

pz.rich_text(["Click ", pz.span("here", color="#74ade8", underline=True, link=self.open), " to open."])

span

span(
    text,
    *,
    color=None,
    size=None,
    font=None,
    weight=None,
    italic=False,
    bg=None,
    radius=0.0,
    padding=None,
    underline=False,
    strikethrough=False,
    link=None,
)

A styled span for rich_text. With link, clicking it sends (or calls) that value.

Parameter	Description
text	The text.
color	Text or icon color.
size	Size.
font	Font of the span or text (family name, e.g. "IBM Plex Mono").
weight	Font weight: "normal", "medium", "semibold" or "bold".
italic	If True, the span is drawn in italics.
bg	Background color ("#rrggbb[aa]", (r, g, b[, a]) or "transparent").
radius	Background radius.
padding	Inner padding: 8, (vertical, horizontal) or (top, right, bottom, left).
underline	Underline.
strikethrough	Strikethrough.
link	Message or callable on click.

Span

The type of the spans created by pz.span.

qr_code

qr_code(data, *, cell_size=4.0, color=None, bg=None)

A QR code that encodes data.

Parameter	Description
data	The text or URL to encode.
cell_size	Size of each module in pixels.
color	Text or icon color.
bg	Background color ("#rrggbb[aa]", (r, g, b[, a]) or "transparent").

shader

shader(
    code,
    *,
    uniforms=None,
    textures=None,
    width=None,
    height=None,
    animate=True,
    time=None,
    fallback=None,
)

A widget painted on the GPU by your WGSL fn shade(uv, px, size, time) -> vec4<f32>, which returns each pixel’s color, or by a shader graph made of nodes (a .pzshad path or a pyzed.shading Graph or Shader). Each entry of uniforms becomes a function of the same name ({"speed": 2} -> speed()); mouse() gives the pointer. Without a GPU the widget shows fallback. Raises ValueError with the compiler’s message for invalid code. See the shaders guide.

Parameter	Description
code	WGSL source that defines shade (and any helper functions), or a .pzshad path, Graph or Shader.
uniforms	Up to 32 named values: a number, 2 to 4 numbers or a color. With a .pzshad, the shader’s mutable variables by name.
textures	Up to 8 images, {name: path}: each becomes name(uv), the image’s color at uv.
width	Width ("fill" by default).
height	Height ("fill" by default).
animate	Redraw every frame so time moves (True).
time	A fixed time in seconds, for a still frame.
fallback	Color or gradient shown without a GPU.

canvas

canvas(
    shapes=None,
    *,
    width=None,
    height=None,
    id=None,
    on_press=None,
    on_release=None,
    on_right_press=None,
    on_move=None,
    on_scroll=None,
    cursor=None,
)

A 2D drawing surface. shapes is a list created with pyzed.draw. Mouse callbacks receive coordinates relative to the canvas. With an id, the geometry is cached between frames and only recomputed when the shapes change. See the drawing with canvas guide.

Parameter	Description
shapes	List of pyzed.draw shapes (nested lists are accepted).
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
id	Enables the geometry cache.
on_press	Callable that receives (x, y) on press.
on_release	Callable that receives (x, y) on release.
on_right_press	Callable that receives (x, y) on right click.
on_move	Called with (x, y) when the mouse moves.
on_scroll	Callable that receives (dx, dy) in lines when the wheel is used.
cursor	Mouse cursor ("crosshair", "pointer"…).

Interaction

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.

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

text_input

text_input(
    value,
    *,
    placeholder='',
    on_input=None,
    on_submit=None,
    id=None,
    size=None,
    font=None,
    padding=None,
    width=None,
    secure=False,
    icon=None,
    icon_size=None,
    bg=None,
    border_color=None,
    hover_border_color=None,
    focus_border_color=None,
    border_width=None,
    radius=None,
    color=None,
    placeholder_color=None,
    selection_color=None,
    icon_color=None,
    align_x=None,
)

A controlled text field: it shows value and notifies you of changes through on_input. For the themed field use ui.input.

Parameter	Description
value	Current text.
placeholder	Hint text shown when empty.
on_input	Callable that receives the new text on every keystroke.
on_submit	Message or callable sent when Enter is pressed.
id	Stable identifier used to focus or scroll it with a Command.
size	Font size.
font	Font family.
padding	Inner padding: 8, (vertical, horizontal) or (top, right, bottom, left).
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
secure	Hides the text (passwords).
icon	Icon character (use pyzed.icons.glyph(name)).
icon_size	Icon size.
bg	Background color ("#rrggbb[aa]", (r, g, b[, a]) or "transparent").
border_color	Border color.
hover_border_color	Border color on hover.
focus_border_color	Border color when focused.
border_width	Border width in pixels.
radius	Corner radius: a number or (top_left, top_right, bottom_right, bottom_left).
color	Text or icon color.
placeholder_color	Placeholder color.
selection_color	Selection color.
icon_color	Icon color.
align_x	Horizontal alignment: "start"/"left", "center", "end"/"right".

mouse_area

mouse_area(
    content,
    *,
    on_press=None,
    on_release=None,
    on_right_press=None,
    on_double_click=None,
    on_enter=None,
    on_exit=None,
    on_move=None,
    on_scroll=None,
    on_middle_press=None,
    on_middle_release=None,
    cursor=None,
)

Detects mouse events over its content.

Parameter	Description
content	Content: a Widget, a string or a number (converted to text).
on_press	Left click (on press).
on_release	On releasing the left button.
on_right_press	Right click (context menus).
on_double_click	Double click.
on_enter	The mouse enters.
on_exit	The mouse leaves.
on_move	Called with (x, y) when the mouse moves.
on_scroll	Callable that receives (dx, dy) in lines when the wheel is used.
on_middle_press	Middle-button click.
on_middle_release	Middle button released (pan gestures, for example).
cursor	"pointer", "text", "grab", "grabbing", "crosshair", "not-allowed", "resize-horizontal", "resize-vertical", "move" or "default".

hover

hover(base, top)

Shows top over base only while the mouse is over it (for example, a tab’s close button).

Parameter	Description
base	Widget underneath.
top	Widget that appears on hover.

opaque

opaque(content)

Makes a widget block the mouse for whatever is below it in a stack.

Parameter	Description
content	Content: a Widget, a string or a number (converted to text).

tooltip

tooltip(
    content,
    tip,
    *,
    position='bottom',
    gap=4.0,
    bg=None,
    color=None,
    border_color=None,
    border_width=0.0,
    radius=None,
    shadow=None,
)

Shows tip next to content on hover. ui.tooltip adds the theme’s style.

Parameter	Description
content	Content: a Widget, a string or a number (converted to text).
tip	Tooltip content.
position	"top", "bottom", "left", "right" or "cursor".
gap	Distance from the content.
bg	Background color ("#rrggbb[aa]", (r, g, b[, a]) or "transparent").
color	Text or icon color.
border_color	Border color.
border_width	Border width in pixels.
radius	Corner radius: a number or (top_left, top_right, bottom_right, bottom_left).
shadow	Shadow: (color, (dx, dy), blur).

popup

popup(base, content=None, *, on_dismiss=None, side='bottom', align='start', gap=4.0)

Shows content over everything else next to base, like the menu of a drop-down: it is not cut off by the panels base sits in, flips to the other side when it does not fit and stays inside the window. A press outside it (and outside base) or Escape calls on_dismiss. With content=None only base is shown. The date pickers open their calendars with it.

Parameter	Description
base	The widget it belongs to (a field, a button).
content	What opens (a panel, a menu), or None while closed.
on_dismiss	Message or callable sent on a press outside or Escape.
side	"bottom", "top", "right" or "left" of base.
align	"start", "center" or "end": how it lines up with base.
gap	Space between base and the content.

pz.popup(field, panel if self.open else None, on_dismiss=self.close)

Controls

checkbox

checkbox(
    checked,
    label=None,
    *,
    on_toggle=None,
    size=None,
    text_size=None,
    accent=None,
    bg=None,
    border_color=None,
    check_color=None,
    color=None,
)

A checkbox.

Parameter	Description
checked	Current state.
label	Label text.
on_toggle	Callable that receives the new bool (or a message to send).
size	Box size.
text_size	Text size.
accent	Accent color (active part).
bg	Background color ("#rrggbb[aa]", (r, g, b[, a]) or "transparent").
border_color	Border color.
check_color	Check mark color.
color	Text or icon color.

toggler

toggler(
    checked,
    label=None,
    *,
    on_toggle=None,
    size=None,
    text_size=None,
    accent=None,
    bg=None,
    border_color=None,
    knob_color=None,
    color=None,
)

An on/off switch.

Parameter	Description
checked	Current state.
label	Label text.
on_toggle	Callable that receives the new bool (or a message to send).
size	Switch height.
text_size	Text size.
accent	Accent color (active part).
bg	Background color ("#rrggbb[aa]", (r, g, b[, a]) or "transparent").
border_color	Border color.
knob_color	Knob color.
color	Text or icon color.

slider

slider(
    min,
    max,
    value,
    *,
    step=1.0,
    on_change=None,
    on_release=None,
    width=None,
    height=None,
    vertical=False,
    accent=None,
    bg=None,
    knob_color=None,
    border_color=None,
)

A slider between min and max.

Parameter	Description
min	Minimum.
max	Maximum.
value	Current value.
step	Step.
on_change	Callable that receives the new value.
on_release	Sent when the knob is released.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
vertical	Vertical orientation.
accent	Accent color (active part).
bg	Background color ("#rrggbb[aa]", (r, g, b[, a]) or "transparent").
knob_color	Knob color.
border_color	Border color.

progress_bar

progress_bar(
    value,
    *,
    min=0.0,
    max=1.0,
    width=None,
    height=None,
    accent=None,
    bg=None,
    radius=2.0,
)

A progress bar.

Parameter	Description
value	Current value.
min	Minimum.
max	Maximum.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
accent	Accent color (active part).
bg	Background color ("#rrggbb[aa]", (r, g, b[, a]) or "transparent").
radius	Corner radius.

vertical_slider

vertical_slider(min, max, value, **kwargs)

A vertical slider (slider(..., vertical=True)).

Parameter	Description
min	Minimum.
max	Maximum.
value	Current value.
kwargs	Same as slider.

pick_list

pick_list(
    options,
    selected=None,
    on_select=None,
    *,
    on_open=None,
    on_close=None,
    placeholder=None,
    width=None,
    padding=None,
    text_size=None,
    font=None,
    handle=None,
    handle_size=12.0,
    menu_height=None,
    bg=None,
    color=None,
    placeholder_color=None,
    handle_color=None,
    border_color=None,
    hover_border_color=None,
    radius=None,
    menu_bg=None,
    menu_color=None,
    menu_border_color=None,
    selected_bg=None,
    selected_color=None,
    focus_border_color=None,
    id=None,
)

A dropdown to choose one of options. on_select(option) receives the chosen one. For the themed dropdown use ui.select. It takes the keyboard focus like a text field (a click, Tab or Command.focus(id)) and keeps it after a choice: ↑/↓ then pick the previous or next option without opening it, Home/End the first and last and typing jumps to an option; Enter, Space, Alt+↓ or F4 open the menu, where ↑/↓ move, Enter picks and Esc closes.

Parameter	Description
options	List of options.
selected	Current option.
on_select	Callable that receives the chosen item.
on_open	Sent when the menu opens.
on_close	Sent when the menu closes.
placeholder	Hint text shown when empty.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
padding	Inner padding: 8, (vertical, horizontal) or (top, right, bottom, left).
text_size	Text size.
font	Font family.
handle	Arrow icon character.
handle_size	Arrow size.
menu_height	Maximum menu height.
bg	Background color ("#rrggbb[aa]", (r, g, b[, a]) or "transparent").
color	Text or icon color.
placeholder_color	Placeholder color.
handle_color	Arrow color.
border_color	Border color.
hover_border_color	Border color on hover.
radius	Corner radius: a number or (top_left, top_right, bottom_right, bottom_left).
menu_bg	Menu background.
menu_color	Menu text.
menu_border_color	Menu border.
selected_bg	Background of the highlighted option.
selected_color	Text of the highlighted option.
focus_border_color	Border color while it has the keyboard focus.
id	Stable identifier used to focus or scroll it with a Command.

radio

radio(
    label,
    selected,
    on_select=None,
    *,
    size=None,
    text_size=None,
    spacing=None,
    accent=None,
    bg=None,
    border_color=None,
    color=None,
)

A radio button. Group several yourself (or use ui.radio_group); on_select is sent when it is clicked.

Parameter	Description
label	Label text.
selected	Whether it is checked.
on_select	Message or callable on click.
size	Size.
text_size	Text size.
spacing	Space between the circle and the text.
accent	Accent color (active part).
bg	Background color ("#rrggbb[aa]", (r, g, b[, a]) or "transparent").
border_color	Border color.
color	Text or icon color.

Code editor

code_editor

code_editor(
    id,
    text='',
    *,
    language='txt',
    size=14.0,
    line_height=None,
    font=None,
    width=None,
    height=None,
    padding=None,
    syntax=None,
    bg=None,
    color=None,
    selection_color=None,
    placeholder=None,
    placeholder_color=None,
    gutter=True,
    gutter_color=None,
    gutter_active_color=None,
    gutter_width=None,
    markers=None,
    wrap=False,
    on_change=None,
    on_cursor=None,
    active_line=None,
    scrollbar_color=None,
    annotations=None,
    whitespace=None,
    tab_size=None,
    capture_keys=None,
    on_scroll=None,
    auto_close=False,
    folding=False,
    minimap=None,
    minimap_thumb=None,
    cursor_shape='bar',
    cursor_width=2.0,
    cursor_blink=True,
    cursor_color=None,
    on_zoom=None,
    on_action=None,
    highlights=None,
    highlight_color=None,
    match_brackets=True,
    selection_highlight=True,
    keymap=None,
    scrollbar=True,
    readonly=False,
    hard_tabs=False,
    backspace_unindent=True,
    repeat_delay=None,
    repeat_rate=None,
    on_hover=None,
    hover_delay=500.0,
    sticky_scroll=0,
)

A code editor with syntax highlighting, line numbers and git markers, based on Iced’s text_editor. It is uncontrolled: text is only the initial value for that id; the text, cursor and history live in Rust. Use Command.set_editor_text to replace it. For the themed editor use ui.editor.

Parameter	Description
id	Identifies the buffer. Reuse it to keep state across renders.
text	Initial text.
language	Language extension or name ("py", "rs", "json"…).
size	Font size.
line_height	Line height in pixels.
font	Family (monospace by default).
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
padding	Inner padding: 8, (vertical, horizontal) or (top, right, bottom, left).
syntax	Map of TextMate scopes to colors (provided by Theme.syntax_scopes()).
bg	Background color ("#rrggbb[aa]", (r, g, b[, a]) or "transparent").
color	Text or icon color.
selection_color	Selection color.
placeholder	Hint text shown when empty.
placeholder_color	Placeholder color.
gutter	Shows line numbers.
gutter_color	Line number color.
gutter_active_color	Color of the cursor line’s number.
gutter_width	Gutter width (automatic by default).
markers	{line: color} for git markers in the gutter (lines from 1).
wrap	Line wrapping.
on_change	Callable that receives the full text after each edit.
on_cursor	Callable that receives (line, column), from 1.
active_line	Background color of the cursor line.
scrollbar_color	Scrollbar color.
annotations	{line: "text"} or {line: ("text", color)}: virtual text at the end of the line (code lens, diagnostics).
whitespace	Draws spaces as · and tabs as → in this color.
tab_size	Tab inserts spaces up to the next multiple; Enter keeps the indentation; Backspace removes a level.
capture_keys	Keys the editor leaves to the app’s on_key ("up", "enter"…), e.g. while a completion list is open.
on_scroll	Called on scroll.
auto_close	Typing a bracket or quote also inserts its closing pair.
folding	Fold chevrons in the gutter and Ctrl+Shift+[ / ].
minimap	Width of the minimap in pixels (None: no minimap).
minimap_thumb	Color of the minimap’s visible-area highlight.
cursor_shape	"bar", "block", "underline" or "hollow".
cursor_width	Width of the bar cursor.
cursor_blink	Whether the cursor blinks.
cursor_color	Cursor color.
on_zoom	Callable that receives 1, -1 or 0 for Ctrl+= / Ctrl+- / Ctrl+0 and Ctrl+wheel.
on_action	Callable that receives the name of each editor action that runs ("undo", "select_next"…).
highlights	Ranges painted behind the text (search results): [(line, column, end_line, end_column)], from 1, with exclusive ends.
highlight_color	Color of highlights.
match_brackets	Outlines the bracket that matches the one next to the cursor.
selection_highlight	Highlights the other occurrences of the selected text.
keymap	Zed-style {binding: action} dict; None as the action removes a default key (pyzed.ui.editor.keymap_for builds one from per-action overrides).
scrollbar	False hides the scrollbars.
readonly	True lets the text be selected and copied but not changed (a log, a traceback).
hard_tabs	With tab_size: Tab, Enter and indent (Ctrl+]) use tab characters instead of spaces.
backspace_unindent	With tab_size: Backspace in leading spaces removes a whole level (False: one space).
repeat_delay	Milliseconds Backspace and Delete wait, held down, before repeating (None: the system’s).
repeat_rate	Deletions per second at most while Backspace or Delete is held down (None: the system’s pace).
on_hover	Callable that receives {line, column, start, end, x, y, height} (the word under the mouse, from 1, and its place in the editor) after the mouse rests on it, and None when it leaves (hover cards).
hover_delay	Milliseconds the mouse rests on a word before on_hover is called.
sticky_scroll	How many lines of the enclosing blocks (class, def, if…) stay pinned at the top while scrolling (0: none).

Styles

Style

class Style

A reusable set of style properties for widget.style(...), a component’s style= or App.style. Combine styles with | (the right one wins). See Styles.

Parameter	Description
styles	Styles, dicts or style names to start from.
props	Properties: background, color, font, weight, italic, size, line_height, border_color, border_width, border ((width, color)), radius, shadow, padding, margin, width, height, max_width, max_height, min_width, min_height, align_x, align_y, clip. Effects: opacity, translate ((x, y), pixels or "50%"), scale, glow (a color, a size or (color, size)), bloom (a color or (color, intensity)) and glass (True, a tint or {"tint", "strength"}). States: hover, pressed (or active) and focus, each with the properties to show then. transition: milliseconds, True or {"duration", "easing", "delay"}. media: {query: style} applied when the window matches. Colors may be theme tokens.

card = pz.Style(background="panel", border=(1, "border"), radius=8, padding=12)
pz.column([...]).style(card | pz.Style(shadow=("#0006", (0, 4), 12)))

Methods and properties

Style.get

Style.get(key, default=None)

Returns a property’s value (aliases accepted), or default when it is not set.

Style.merge

Style.merge(*styles, **props)

A new style with styles and props on top of this one.

Style.without

Style.without(*keys)

A new style without these properties.

Style.text

Style.text()

Only the text properties (what a style passes down to the texts inside).

Style.to_dict

Style.to_dict()

JSON-friendly properties (gradients and paints become dicts).

Style.from_dict

@classmethod
Style.from_dict(data)

Builds a style from data made by to_dict (aliases accepted).

define_style

define_style(name, *styles, **props)

Names a style so widgets can use it by name: widget.style("card"). Returns it.

Parameter	Description
name	The style’s name.
styles	Styles to merge.
props	Properties on top.

stylesheet

stylesheet(rules=None, **classes)

Adds CSS-like rules, {selector: style}, that widgets get with widget.classes(...) and components with class_=/id=. Selectors: .class, .a.b, #id, a component’s class name ("Rating"), an optional :hover, :pressed/:active or :focus, and comma lists. More specific selectors win (ids, then classes, then names), then later rules. A selector given again replaces its rule. Returns every rule. See Stylesheets.

Parameter	Description
rules	A {selector: style} dict.
classes	Classes by keyword: card={...} is ".card".

pz.stylesheet({
    ".card": {"background": "panel", "padding": 16, "radius": 8},
    ".card:hover": {"border_color": "accent"},
})
pz.column([...]).classes("card")

clear_stylesheet

clear_stylesheet()

Removes every rule added with pz.stylesheet.

media

media(query=None, **conditions)

Whether the window being drawn matches a media query, like CSS @media. See Responsive styles.

Parameter	Description
query	"max_width: 600", "(min_width: 768px) and (orientation: landscape)" or a breakpoint ("md").
conditions	The same by keyword: min_width, max_width, min_height, max_height, orientation, theme.

sidebar = None if pz.media("max_width: 600") else self.sidebar()

viewport

viewport()

The size of the window being drawn, (width, height) in logical pixels, like window.innerWidth and innerHeight.

current_breakpoint

current_breakpoint()

The widest breakpoint the window reaches: "xs" (under 640 px), "sm", "md", "lg", "xl" or "xxl".

set_style

set_style(*styles, **props)

Sets the global style for every window, under each window’s style. Without arguments it clears it.

Parameter	Description
styles	Styles to merge.
props	Properties on top.

Gradient

class Gradient

A linear gradient for backgrounds. Angles follow CSS: 0 up, 90 right, 180 (the default) down. Up to 8 stops.

Parameter	Description
stops	Colors, spread evenly, or (offset, color) pairs with offsets from 0 to 1.
angle	Direction in degrees.

pz.container(None, height=80).style(background=pz.Gradient(["#f97316", "#7c3aed"], angle=90))

Methods and properties

Gradient.to_value

Gradient.to_value()

(angle, [(offset, "#rrggbbaa"), ...]), the form widgets take as gradient=.

Gradient.to_dict

Gradient.to_dict()

Returns the gradient as JSON-ready data: {"type": "linear", "angle", "stops"}.

Mask

class Mask

An opacity mask for a Paint: how visible the fill is along a direction. On a gradient it follows the gradient’s direction.

Parameter	Description
stops	Opacities (0 to 1), spread evenly, or (offset, opacity) pairs.
angle	Direction when the fill is a plain color.

Methods and properties

Mask.at

Mask.at(offset)

Returns the opacity (0 to 1) at offset (0 to 1), interpolating between stops.

Mask.to_dict

Mask.to_dict()

Returns the mask as JSON-ready data: {"angle", "stops"}.

Paint

class Paint

A fill: a color or Gradient with an overall opacity and an optional Mask. Works anywhere a background does.

Parameter	Description
fill	A color or a Gradient.
opacity	0 to 1, multiplies the fill’s own alpha.
mask	A pz.Mask.

pz.Paint("#3b82f6", opacity=0.8, mask=pz.Mask([1, 0]))  # fades out downwards

Methods and properties

Paint.resolve

Paint.resolve()

(color, gradient): what a container draws (one of them is None).

Paint.to_dict

Paint.to_dict()

Returns the paint as JSON-ready data: fill, opacity and mask when there is one.

global_style

global_style()

The style set with set_style (None if none).

named_styles

named_styles()

The styles defined with define_style, by name.

apply_global

apply_global(view, style=None)

view with a window’s global style: text properties fill in what texts leave unset.

themed

themed(theme, style)

theme with a global style’s text color, background, border color, size and radius.

to_hex

to_hex(color)

Any color as "#rrggbb" or "#rrggbbaa" (theme tokens resolved).

paint_from_dict

paint_from_dict(data)

Rebuilds a Gradient or Paint saved with to_dict().

Animation

Animation

@dataclass
class Animation(keyframes=(), duration=300, delay=0, easing='ease', repeat=1, direction='normal', fill='both', on='mount', category='custom', description='', _frames=())

A keyframe animation, like a CSS @keyframes rule with its timing.

keyframes is a list of {property: value} frames (spread evenly; a frame may set offset and easing) or a dict from offsets (0 to 1, "50%", "from", "to") to frames. A property missing at the start or end goes from or to the widget’s own value, and None names that value explicitly:

pz.Animation([{"opacity": 0, "y": 12}, {"opacity": 1, "y": 0}], duration=250)
pz.Animation({0: {"scale": 1}, "50%": {"scale": 1.1}, 1: {"scale": 1}}, repeat="infinite")

The other fields are the defaults animate() options override. category and description tell editors where and how to show a preset.

Methods and properties

Animation.properties

Animation.properties  # property

The properties the keyframes change, in order of appearance.

Animation.total

Animation.total  # property

Milliseconds from the start to the end (inf when it repeats forever).

Animation.with_options

Animation.with_options(**options)

A copy with other timing or trigger (duration, easing, on…).

Animation.compile

Animation.compile(**options)

The plain data the native side plays (animate() calls it).

Animation.to_dict

Animation.to_dict()

JSON-ready data (Animation.from_dict reads it back).

Animation.from_dict

@classmethod
Animation.from_dict(data)

Rebuilds an animation saved with to_dict.

Trigger

class Trigger

Starts an animation from your code, like a button you press in a handler.

Keep one on the app, give it to animate(on=...) in view() and call fire() whenever the animation should play (from the start, even if it is still running):

class Login(pz.App):
    def __init__(self):
        self.wrong = pz.Trigger()

    def view(self):
        return ui.input(self.password, self.set_password).animate("shake", on=self.wrong)

    def submit(self):
        if not self.check():
            self.wrong.fire()          # the field shakes now

Nothing plays when the widget appears: only fire() starts it. count says how many times it was fired. fire takes and ignores any arguments, so it can be a callback itself: ui.button("Shake", self.wrong.fire).

Methods and properties

Trigger.fire

Trigger.fire(*_args)

Plays the animations that use this trigger, from the start.

define_animation

define_animation(name, animation=None, **options)

Names an animation so animate(name) plays it; returns it.

define_animation("wiggle", [{"x": 0}, {"x": -4}, {"x": 4}, {"x": 0}], duration=300)

presence

presence(
    content,
    key,
    *,
    enter='fade_in',
    exit='fade_out',
    id=None,
    duration=None,
    easing=None,
)

Shows content and, when key changes, animates the old content out (exit) while the new one comes in (enter), like page transitions:

pz.presence(self.page_view(), key=self.page, enter="slide_in_right", exit="fade_out")

id tells presences apart (it defaults to where it is called from, so give one when the same line makes several). duration and easing override both animations’.

stagger

stagger(items, animation='fade_in_up', *, step=40, delay=0, **options)

items with the same animation, each starting step milliseconds after the previous one (a list that cascades in):

pz.column(pz.stagger([row(i) for i in items], "fade_in_up", step=30))

set_reduced_motion

set_reduced_motion(on=True)

Turns motion off (True) or back on: animations show their resting state at once.

By default Pyzed follows the system’s “reduce motion” accessibility setting (read when the app starts, see pyzed.system_reduced_motion). True or False overrides it (for example from your app’s own settings, or in tests) and None follows the system again. The PYZED_REDUCED_MOTION environment variable (1 or 0) overrides it too.

reduced_motion

reduced_motion()

Whether reduced motion is on.

system_reduced_motion

system_reduced_motion()

Whether the system asks apps to reduce motion (None if unknown).

animation

animation(name)

The animation named name (a preset or one defined with define_animation).

presets

presets(category=None)

The named animations (all, or one category: entrance, exit, attention, interaction, loop).

ease

ease(easing, t)

easing at t (0 to 1), the curve animations use: ease("ease_out", 0.5).

Handy to animate your own drawings (pz.canvas) with the same curves.

window_animations

window_animations(window, closing=False)

The animation a window plays when it opens (or closes), from its transition and exit_transition (an empty list when it has none).

PRESETS

Every named animation (the built-in presets and the ones added with define_animation), mapped to its Animation. See the preset list.

CATEGORIES

Preset categories: entrance, exit, attention, interaction and loop.

EASINGS

Easing names (linear, ease, ease_out_cubic, ease_out_back, spring…). animate() also takes (x1, y1, x2, y2) cubic Béziers and "steps(n)".

TRIGGERS

What plays an animation: mount, hover, press, focus, click, active and manual (each time key changes; a pz.Trigger given to on= uses it).

PROPERTIES

The properties animations and transitions change: opacity, x, y, scale, background, border_color, color, radius, border_width, glow and glow_color.

WINDOW_TRANSITIONS

Names for Window.transition (fade, zoom, pop, slide_up, slide_down, slide_left, slide_right) mapped to their (opening, closing) presets.

Timeline animations

Clip

@dataclass
class Clip(name, length=None, tracks=(), calls=(), loop='none', description='')

A named timeline of length seconds with tracks and calls (see the module docs).

loop is "none" (plays once and holds the last frame), "loop" or "pingpong". length defaults to the time of the last key or call.

Methods and properties

Clip.targets

Clip.targets  # property

The widget targets its tracks animate, in order.

Clip.attributes

Clip.attributes  # property

The app attributes its tracks animate (":score" -> "score").

Clip.track

Clip.track(path)

The track with path (None when there is none).

Clip.values

Clip.values(time, target=None)

{path: value} of the enabled tracks at time (only target’s, as {property: value}).

Clip.with_track

Clip.with_track(track)

A copy with track added, or replacing the track with the same path.

Clip.without_track

Clip.without_track(path)

A copy without the track path.

Clip.with_key

Clip.with_key(path, time, value, easing=None)

A copy with a key at time on path (replacing one at the same time; adds the track).

Clip.without_key

Clip.without_key(path, time)

A copy without the key at time on path.

Clip.retarget

Clip.retarget(mapping, name=None)

A copy whose tracks animate other widgets: clip.retarget({"card": "panel"}).

Clip.animation

Clip.animation(target, *, on='mount', **options)

target’s tracks as a pz.Animation (to play without a player, or define_animation).

Clip.to_dict

Clip.to_dict()

JSON-ready data (Clip.from_dict reads it back).

Clip.from_dict

@classmethod
Clip.from_dict(data)

Rebuilds a clip saved with to_dict.

Track

@dataclass
class Track(path, keys=(), easing='linear', interpolation='linear', enabled=True)

One property changing over time: Track("card:opacity", {0: 0, 0.5: 1}).

keys is {time: value}, a list of (time, value) or (time, value, easing) tuples, or Key objects. easing is the default curve between keys ("linear", like Godot) and interpolation="discrete" holds each value until the next key. enabled=False keeps a track in the clip without playing it.

Methods and properties

Track.target

Track.target  # property

The widget target ("" for an app attribute).

Track.property

Track.property  # property

The property or attribute path it changes.

Track.value_at

Track.value_at(time)

The track’s value at time seconds (None when it has no keys).

Track.with_keys

Track.with_keys(keys)

A copy with other keys.

Track.to_dict

Track.to_dict()

JSON-ready data (Track.from_dict reads it back).

Track.from_dict

@classmethod
Track.from_dict(data)

Rebuilds a track saved with to_dict.

Key

@dataclass
class Key(time, value, easing=None)

A value at a time on a track; easing is the curve to the next key (the track’s when None).

Methods and properties

Key.to_dict

Key.to_dict()

JSON-ready data (Key.from_dict reads it back).

Key.from_dict

@classmethod
Key.from_dict(data)

Rebuilds a key saved with to_dict.

Call

@dataclass
class Call(time, method, args=())

A method called at time seconds: Call(1.2, "play_sound", "ding").

method is the name of a method of the app (the player’s owner) or a callable; args are passed to it. What it returns (a Command, a message…) is handled like a callback’s.

Methods and properties

Call.to_dict

Call.to_dict()

JSON-ready data (only calls to methods by name can be saved).

Call.from_dict

@classmethod
Call.from_dict(data)

Rebuilds a call saved with to_dict.

AnimationPlayer

class AnimationPlayer

Plays Clips on widgets and app state, with play, pause, seek, speed and a queue.

sources are clips, AnimationLibrary objects and .pzanim paths. Give widgets their target with widget.animate(player["card"]); tracks of app attributes (":score") and Calls run on the player’s owner, which is the app (or window) that holds the player in an attribute, found automatically, or the one you pass.

• autoplay: the clip that plays when the player is created.
• speed: the playback speed of every clip (play multiplies it).
• on_started(name)/on_finished(name): called when a clip starts and when it ends (never for looping clips); they may take no argument.
• fps: how often app attributes update while a clip with attribute tracks plays.

Events:

• on_started(name): Called with the name of a clip when it starts.
• on_finished(name): Called with the name of a clip when it ends (never for looping clips).

Methods and properties

AnimationPlayer.add

AnimationPlayer.add(source, *, prefix=None)

Adds a clip, a library (its clips as "name/clip" when it has a name) or a .pzanim path.

AnimationPlayer.remove

AnimationPlayer.remove(name)

Removes the clip name (stopping it when it is the current one).

AnimationPlayer.names

AnimationPlayer.names  # property

The names of the clips it can play.

AnimationPlayer.has

AnimationPlayer.has(name)

Whether it has a clip called name.

AnimationPlayer.clip

AnimationPlayer.clip(name=None)

The clip named name (the current one by default).

AnimationPlayer.target

AnimationPlayer.target(target, *, only=None)

Like player[target]; only keeps some properties (("opacity", "x", "y")), for example to move what sits inside an animated container along with it.

AnimationPlayer.current

AnimationPlayer.current  # property

The clip playing or paused (None when stopped).

AnimationPlayer.playing

AnimationPlayer.playing  # property

Whether time is moving.

AnimationPlayer.paused

AnimationPlayer.paused  # property

Whether a clip is paused (stopped clips and finished ones aren’t).

AnimationPlayer.finished

AnimationPlayer.finished  # property

Whether the current clip reached its end.

AnimationPlayer.length

AnimationPlayer.length  # property

The length of the current clip in seconds (0 when none).

AnimationPlayer.position

AnimationPlayer.position  # property

Seconds into the current clip.

AnimationPlayer.queued

AnimationPlayer.queued  # property

The clips that play after the current one, in order.

AnimationPlayer.value

AnimationPlayer.value(path)

The value the current clip gives path ("card:opacity", ":score") right now.

AnimationPlayer.play

AnimationPlayer.play(name=None, *, speed=1.0, backwards=False, from_end=False, restart=False)

Plays name (the current or paused clip by default) from where it is.

AnimationPlayer.play_backwards

AnimationPlayer.play_backwards(name=None, *, speed=1.0)

Plays name in reverse from its end (or the current clip from where it is).

AnimationPlayer.pause

AnimationPlayer.pause()

Stops time where it is (play() or resume() goes on).

AnimationPlayer.resume

AnimationPlayer.resume()

Goes on from where the clip was paused.

AnimationPlayer.toggle

AnimationPlayer.toggle()

Pauses when playing, plays otherwise.

AnimationPlayer.stop

AnimationPlayer.stop(*, reset=False)

Stops at the start of the clip (showing its first frame); reset lets widgets go back to their own values and forgets the clip. Clears the queue.

AnimationPlayer.seek

AnimationPlayer.seek(seconds)

Jumps to seconds into the current clip (calls on the way don’t run).

AnimationPlayer.advance

AnimationPlayer.advance(seconds)

Moves the current clip seconds forward (calls run, state updates), like Godot’s advance.

AnimationPlayer.queue

AnimationPlayer.queue(name)

Plays name after the current clip ends (or now when nothing plays).

AnimationPlayer.clear_queue

AnimationPlayer.clear_queue()

Forgets the queued clips.

AnimationPlayer.subscriptions

AnimationPlayer.subscriptions()

What keeps the player’s calls, attribute tracks and queue going (added for you when the player is an attribute of the app or a window).

AnimationLibrary

class AnimationLibrary

Named clips that are saved together in a .pzanim file and reused.

AnimationLibrary([intro, idle], name="ui"); lib["intro"], lib.add(clip), lib.remove("idle"), lib.save("ui.pzanim") and AnimationLibrary.load(path). A player given a library with a name calls its clips "ui/intro", like Godot.

Methods and properties

AnimationLibrary.add

AnimationLibrary.add(clip)

Adds clip (replacing one with its name) and returns it.

AnimationLibrary.remove

AnimationLibrary.remove(name)

Removes the clip name (nothing happens when there is none).

AnimationLibrary.rename

AnimationLibrary.rename(old, new)

Renames the clip old to new and returns it.

AnimationLibrary.names

AnimationLibrary.names  # property

The names of its clips, in order.

AnimationLibrary.to_dict

AnimationLibrary.to_dict()

The .pzanim data (AnimationLibrary.from_dict reads it back).

AnimationLibrary.from_dict

@classmethod
AnimationLibrary.from_dict(data)

Rebuilds a library from .pzanim data.

AnimationLibrary.save

AnimationLibrary.save(path)

Writes the library as JSON (a .pzanim file) and returns the path.

AnimationLibrary.load

@classmethod
AnimationLibrary.load(path)

Reads a .pzanim file (raises ValueError when it isn’t one).

load_animations

load_animations(path)

The library saved in a .pzanim file.

Large data

virtual_column

virtual_column(count, item, *, item_height, spacing=0.0, overscan=4, width=None)

A column of count rows of the same height that only builds the rows in view: item(index) is called when row index scrolls into view, and rows that leave it are dropped. A column of a million rows costs the same as one of fifty. Put it in a scrollable (it virtualizes against the visible area of the closest one, or the window).

Parameter	Description
count	Number of rows.
item	Function that receives a row index and returns its widget.
item_height	Height of every row, in pixels.
spacing	Space between rows, in pixels.
overscan	Extra rows built above and below the visible ones, so fast scrolling shows no gaps.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).

rows = load_logs()          # a list with 500 000 entries

pz.scrollable(
    pz.virtual_column(len(rows), lambda i: pz.text(rows[i]), item_height=20),
    id="logs", height="fill",
)

memo

memo(function=None, *, maxsize=64)

Decorator that caches what a view function returns by its arguments, so the next view() reuses the same widget tree while they don’t change. Pass everything the subtree depends on as arguments. Lists, dicts and sets compare by contents, other unhashable objects by identity; the current theme and language are always part of the key. function.cache_clear() empties its cache.

Parameter	Description
function	The function to memoize (when used as @pz.memo).
maxsize	How many results to keep per function (least recently used are dropped).

@pz.memo
def sidebar(files: tuple, selected: str):
    return pz.column([ui.list_item(f, selected=f == selected) for f in files])

clear_memos

clear_memos()

Empties the cache of every @pz.memo function.

memo_stats

memo_stats()

Returns {"hits": n, "misses": m}: how many calls of memoized functions were answered from the cache and how many built their result.