Components (pyzed.ui)

Signatures and parameters of every component. To see them with images and examples, go to the Components section.

They are all functions that return a Widget and read their colors from the current theme. Color parameters accept a theme token ("accent", "text_muted", "error"…) or a hex color.

Basics

label

label(
    content,
    *,
    color='text',
    size='md',
    weight=None,
    mono=False,
    italic=False,
    wrap=True,
    theme=None,
    **kwargs,
)

Text with a theme color.

Parameter	Description
content	Content: a Widget, a string or a number (converted to text).
color	Theme token or hex color. Defaults to "text".
size	"xs" (11), "sm" (12), "md" (13.5), "lg" (16), "xl" (20), "2xl" (26) or a number.
weight	Weight: "medium", "semibold", "bold"…
mono	Uses the monospace font (IBM Plex Mono).
italic	Italic.
wrap	Line wrapping.
theme	Theme to use instead of the current one (pyzed.theme.current()).
kwargs	Passed to pyzed.text.

muted

muted(content, **kwargs)

A label with the "text_muted" color.

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

heading

heading(content, *, level=1, theme=None, **kwargs)

A semibold heading.

Parameter	Description
content	Content: a Widget, a string or a number (converted to text).
level	1 (26 px), 2 (20 px), 3 (16 px) or 4 (13.5 px).
theme	Theme to use instead of the current one (pyzed.theme.current()).
kwargs	Same as label.

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.

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

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.

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

badge

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

A small pill for statuses and counters.

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

indicator

indicator(color='accent', *, size=6, theme=None)

A colored dot (status, unsaved changes, presence).

Parameter	Description
color	Token or color.
size	Diameter.
theme	Theme to use instead of the current one (pyzed.theme.current()).

kbd

kbd(keys, *, size='sm', theme=None)

Draws a shortcut as keys: "ctrl-shift-p", "cmd-k cmd-s". Uses symbols on macOS (⌘⇧P) and words elsewhere.

Parameter	Description
keys	The shortcut.
size	"xs" or "sm".
theme	Theme to use instead of the current one (pyzed.theme.current()).

format_keys

format_keys(keys)

Splits a shortcut into labels per chord: format_keys("ctrl-shift-p") == [["Ctrl", "Shift", "P"]]. The style is controlled by pyzed.ui.base.KEY_STYLE ("auto", "symbols" or "words").

Parameter	Description
keys	The shortcut.

keys_text

keys_text(keys)

A shortcut as plain text for a label or a status line: keys_text("ctrl-shift-p") == "Ctrl+Shift+P" ("⌃⇧P" with macOS symbols), chords separated by a space. Tooltips, buttons and menus take keys= instead and draw key caps, so never write the keys into their text.

Parameter	Description
keys	The shortcut.

avatar

avatar(
    initials,
    *,
    color=None,
    size=22,
    index=0,
    image=None,
    status=None,
    tooltip=None,
    theme=None,
)

A round avatar with initials.

Parameter	Description
initials	Initials (the first two are used).
color	Background color.
size	Diameter.
index	Picks a collaborator color from the theme (theme.players).
image	A picture (path or bytes) instead of the initials.
status	Presence dot: "online", "away", "busy", "offline" or a color.
tooltip	Text shown on hover (the person’s name).
theme	Theme to use instead of the current one (pyzed.theme.current()).

tooltip

tooltip(content, text, *, keys=None, position='bottom', theme=None)

Wraps content with a themed tooltip, optionally with its shortcut.

Parameter	Description
content	Content: a Widget, a string or a number (converted to text).
text	Tooltip text.
keys	Shortcut shown at the end, written as a string: "ctrl-s", "cmd-k cmd-s".
position	"top", "bottom", "left", "right" or "cursor".
theme	Theme to use instead of the current one (pyzed.theme.current()).

divider

divider(*, vertical=False, color=None, label=None, spacing=0, theme=None)

A divider line in the theme color.

Parameter	Description
vertical	Vertical instead of horizontal.
color	Text or icon color.
label	Muted text in the middle of a horizontal line ("or", a date…).
spacing	Space on both sides of the line.
theme	Theme to use instead of the current one (pyzed.theme.current()).

card

card(
    content,
    *,
    title=None,
    actions=(),
    padding=16,
    width=None,
    footer=(),
    on_press=None,
    selected=False,
    elevated=False,
    theme=None,
)

A bordered surface to group content, with an optional title and actions.

Parameter	Description
content	Content: a Widget, a string or a number (converted to text).
title	Title.
actions	Extra widgets (usually buttons) shown as actions.
padding	Inner padding.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
footer	Widgets at the bottom right (buttons).
on_press	Makes the whole card clickable.
selected	Outlines it in the accent color.
elevated	Adds a shadow.
theme	Theme to use instead of the current one (pyzed.theme.current()).

Forms

input

input(
    value,
    on_input=None,
    *,
    placeholder='',
    icon=None,
    on_submit=None,
    on_clear=None,
    id=None,
    size='md',
    secure=False,
    width='fill',
    borderless=False,
    mono=False,
    disabled=False,
    readonly=False,
    invalid=False,
    max_length=None,
    align='start',
    theme=None,
)

A text field. Focus, blur and keys come from the common events: .on(focus=..., blur=..., key_down=...).

Parameter	Description
value	Current text.
on_input	Callable that receives the new text on every keystroke.
placeholder	Hint text shown when empty.
icon	Name of a Lucide icon (pyzed icons lists them).
on_submit	Message or callable sent when Enter is pressed.
on_clear	Shows an ✕ while there is text; sent when it is clicked.
id	Stable identifier used to focus or scroll it with a Command.
size	"sm", "md" or "lg".
secure	Hides the text.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
borderless	No border or background (as in the command palette).
mono	Uses the monospace font (IBM Plex Mono).
disabled	Greys it out and ignores typing.
readonly	Selectable and copyable, but it can’t be changed.
invalid	Paints the border in the error color.
max_length	Ignores edits longer than this.
align	Text alignment: "start", "center" or "end".
theme	Theme to use instead of the current one (pyzed.theme.current()).

search_input

search_input(value, on_input=None, *, placeholder='Search…', **kwargs)

An input with a magnifying glass icon.

Parameter	Description
value	Current text.
on_input	Callable that receives the new text on every keystroke.
placeholder	Hint text shown when empty.
kwargs	Same as input.

path_input

path_input(
    value,
    on_change=None,
    *,
    folder=False,
    save=False,
    filters=None,
    kind=None,
    directory=None,
    relative_to=None,
    title=None,
    placeholder=None,
    size='md',
    mono=True,
    disabled=False,
    invalid=False,
    theme=None,
)

A text field for a file or folder path with a button that opens the system’s file dialog, so the path never has to be typed (it still can be).

Parameter	Description
value	Current path.
on_change	Callable that receives the typed or chosen path.
folder	Picks a folder instead of a file.
save	Shows the “Save as” dialog.
filters	(name, extensions) pairs: [("Images", ["png", "jpg"])].
kind	Common filters by name: "image", "audio", "video", "font", "shader" or "data".
directory	Folder the dialog opens in (by default, the current path’s).
relative_to	A chosen path inside this folder is given relative to it.
title	Title of the dialog.
placeholder	Text shown while it is empty.
size	"sm", "md" or "lg".
mono	Monospaced text.
disabled	Greys it out.
invalid	Paints the border in the error color.
theme	Theme to use instead of the current one (pyzed.theme.current()).

ui.path_input(self.logo, self.set_logo, kind="image", relative_to=".")

switch

switch(
    checked,
    on_toggle=None,
    *,
    label=None,
    size='md',
    disabled=False,
    id=None,
    theme=None,
)

An on/off switch.

Parameter	Description
checked	Current state.
on_toggle	Callable that receives the new bool (or a message to send).
label	Label text.
size	"sm", "md" or "lg".
disabled	Greys it out and ignores clicks.
id	Stable identifier used to focus or scroll it with a Command.
theme	Theme to use instead of the current one (pyzed.theme.current()).

checkbox

checkbox(
    checked,
    on_toggle=None,
    *,
    label=None,
    size='md',
    disabled=False,
    id=None,
    theme=None,
)

A checkbox. checked=None shows the mixed state (part of a group checked); clicking it checks it.

Parameter	Description
checked	Current state.
on_toggle	Callable that receives the new bool (or a message to send).
label	Label text.
size	"sm", "md" or "lg".
disabled	Greys it out and ignores clicks.
id	Stable identifier used to focus or scroll it with a Command.
theme	Theme to use instead of the current one (pyzed.theme.current()).

slider

slider(
    value,
    on_change=None,
    *,
    min=0.0,
    max=1.0,
    step=0.01,
    on_release=None,
    vertical=False,
    width=None,
    height=None,
    disabled=False,
    show_value=False,
    id=None,
    theme=None,
)

A slider.

Parameter	Description
value	Current value.
on_change	Callable that receives the new value.
min	Minimum.
max	Maximum.
step	Step.
on_release	Sent when the drag ends (save or apply there).
vertical	Stands it up.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
disabled	Greys it out.
show_value	Shows the number next to it: True, or a format such as "{:.0%}".
id	Stable identifier used to focus or scroll it with a Command.
theme	Theme to use instead of the current one (pyzed.theme.current()).

progress

progress(
    value,
    *,
    max=1.0,
    tint='accent',
    height=4,
    width='fill',
    label=None,
    show_value=False,
    theme=None,
)

A thin progress bar.

Parameter	Description
value	Progress, or None for an indeterminate bar (keep a pz.every(1/30, ...) subscription while it shows).
max	Maximum value.
tint	Semantic color: "accent", "error", "warning", "success", "info" or a token.
height	Thickness.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
label	Text above the bar.
show_value	Adds the percentage at its right.
theme	Theme to use instead of the current one (pyzed.theme.current()).

segmented

segmented(
    options,
    selected,
    on_select=None,
    *,
    size='md',
    width=None,
    disabled=False,
    id=None,
    theme=None,
)

A group of mutually exclusive buttons.

Parameter	Description
options	Strings, (value, label) or (value, label, icon).
selected	The active value.
on_select	Callable that receives the chosen item.
size	"sm", "md" or "lg".
width	"fill" stretches the buttons evenly.
disabled	True, or the values to disable.
id	Stable identifier used to focus or scroll it with a Command.
theme	Theme to use instead of the current one (pyzed.theme.current()).

field

field(
    title,
    control,
    *,
    description=None,
    error=None,
    required=False,
    vertical=False,
    theme=None,
)

A form row: title and description on the left, control on the right (like a settings screen).

Parameter	Description
title	Title.
control	The control (switch, input…).
description	Help text.
error	A validation message shown under the title in the error color (see pz.validation_errors).
required	Adds a red * after the title.
vertical	Puts the control under the title.
theme	Theme to use instead of the current one (pyzed.theme.current()).

Dialogs

dialog_layer

dialog_layer(base, dialog=None, *, on_dismiss=None, theme=None)

Shows a dialog centered over base with a dimmed backdrop. With dialog=None it returns base unchanged, so it can always wrap the view. See Dialogs.

Parameter	Description
base	The UI underneath.
dialog	A dialog from the functions below, or ui.modal.
on_dismiss	Sent when the backdrop is clicked.
theme	Theme to use instead of the current one (pyzed.theme.current()).

ui.dialog_layer(self.main_view(), ui.confirm("Delete 3 files?", self.delete, self.cancel, danger=True)
                if self.asking else None, on_dismiss=self.cancel)

alert

alert(message, on_close, *, title=None, kind=None, ok_label=None, width=400, theme=None)

A message with one button.

Parameter	Description
message	Text or widget.
on_close	The button and the close icon.
title	Title.
kind	"info", "success", "warning" or "error" adds an icon.
ok_label	Button text (default: OK, translated).
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
theme	Theme to use instead of the current one (pyzed.theme.current()).

confirm

confirm(
    message,
    on_confirm,
    on_cancel,
    *,
    title=None,
    confirm_label=None,
    cancel_label=None,
    danger=False,
    kind=None,
    width=420,
    theme=None,
)

Asks a yes/no question.

Parameter	Description
message	Text or widget.
on_confirm	The confirm button.
on_cancel	Cancel, the close icon.
title	Title.
confirm_label	Confirm button text.
cancel_label	Cancel button text.
danger	Paints the confirm button red and labels it Delete.
kind	Adds an icon, as in alert.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
theme	Theme to use instead of the current one (pyzed.theme.current()).

prompt

prompt(
    title,
    value,
    on_input,
    on_submit,
    on_cancel,
    *,
    message=None,
    placeholder='',
    submit_label=None,
    cancel_label=None,
    id=None,
    width=440,
    theme=None,
)

Asks for a line of text.

Parameter	Description
title	Title.
value	Current text.
on_input	Receives each edit.
on_submit	Enter or the submit button.
on_cancel	Cancel, the close icon.
message	Text above the field.
placeholder	Hint text shown when empty.
submit_label	Submit button text.
cancel_label	Cancel button text.
id	Field id (for Command.focus).
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
theme	Theme to use instead of the current one (pyzed.theme.current()).

choice

choice(message, options, on_cancel, *, title=None, width=440, theme=None)

A message with your own buttons.

Parameter	Description
message	Any Python value, or a callable.
options	(label, on_press) pairs; the last one is the main button.
on_cancel	The close icon.
title	Title.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
theme	Theme to use instead of the current one (pyzed.theme.current()).

unsaved_changes

unsaved_changes(name, on_save, on_discard, on_cancel, *, width=440, theme=None)

“Save your changes to name before closing?” with Don’t save, Cancel and Save.

Parameter	Description
name	File or document name.
on_save	Save.
on_discard	Don’t save.
on_cancel	Cancel.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
theme	Theme to use instead of the current one (pyzed.theme.current()).

Controls

select

select(
    options,
    selected=None,
    on_select=None,
    *,
    placeholder='Select…',
    width=None,
    size='md',
    disabled=False,
    invalid=False,
    on_open=None,
    on_close=None,
    id=None,
    theme=None,
)

A dropdown with the theme style. Options are displayed with str(), so strings, enums, dataclasses or database models all work; on_select receives the chosen object, not its label.

Parameter	Description
options	List of options.
selected	Current option.
on_select	Callable that receives the chosen item.
placeholder	Hint text shown when empty.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
size	"sm", "md" or "lg".
disabled	Greys it out.
invalid	Paints the border in the error color.
on_open	Sent when the menu opens.
on_close	Sent when the menu closes.
id	Stable identifier used to focus or scroll it with a Command.
theme	Theme to use instead of the current one (pyzed.theme.current()).

radio_group

radio_group(
    options,
    selected,
    on_select=None,
    *,
    horizontal=False,
    spacing=8,
    disabled=False,
    descriptions=None,
    id=None,
    theme=None,
)

Mutually exclusive options as radio buttons.

Parameter	Description
options	Strings or (value, label) pairs.
selected	Current value.
on_select	Callable that receives the chosen value.
horizontal	In a row instead of a column.
spacing	Space between children, in pixels.
disabled	True, or the values to disable.
descriptions	Maps values to a muted line under their label.
id	Stable identifier used to focus or scroll it with a Command.
theme	Theme to use instead of the current one (pyzed.theme.current()).

number_field

number_field(
    value,
    on_change=None,
    *,
    min=None,
    max=None,
    step=1,
    width=120,
    suffix=None,
    prefix=None,
    align='center',
    decimals=None,
    disabled=False,
    invalid=False,
    id=None,
    on_submit=None,
    steppers=True,
    drag=True,
    drag_step=None,
    theme=None,
)

A numeric field with −/+ buttons that you can also drag, like Figma’s. on_change(value) receives the number already clamped to min/max; anything that can’t be parsed as a number is ignored. Press and move the mouse sideways over the number to change it (it keeps going outside the window); double-click it to type a value, and Enter, Escape or a click outside to finish. Once clicked, ↑/↓ step it (Shift: ten steps) and Home/End jump to min/max.

Parameter	Description
value	Current value.
on_change	Callable that receives the new value.
min	Minimum.
max	Maximum.
step	Button step.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
suffix	Unit shown at the end ("px", "%"…).
prefix	Text before the number ("$"…).
align	Where the number sits between the buttons: "center" (default), "start" or "end".
decimals	Decimals shown (by default, as many as step).
disabled	Greys it out.
invalid	Paints the border in the error color.
id	Stable identifier used to focus or scroll it with a Command.
on_submit	Sent on Enter.
steppers	Shows the −/+ buttons (False: a compact field, as in a property grid).
drag	Lets the mouse change it by dragging (False: a plain text field).
drag_step	How much each pixel dragged adds (by default step, up to 1; steps under 1 take three pixels each).
theme	Theme to use instead of the current one (pyzed.theme.current()).

split_button

split_button(
    content,
    on_press=None,
    on_menu=None,
    *,
    icon=None,
    variant='filled',
    tint=None,
    size='md',
    disabled=False,
    tooltip=None,
    theme=None,
)

A button with a separate arrow for more options. on_press runs the main action and on_menu usually opens a ui.menu in a ui.popover.

Parameter	Description
content	Button text.
on_press	Message or callable sent on press. None disables the control.
on_menu	Message or callable for the menu button.
icon	Name of a Lucide icon (pyzed icons lists them).
variant	As in ui.button.
tint	As in ui.button.
size	"xs", "sm", "md" or "lg".
disabled	Disables both halves.
tooltip	Tooltip of the main half.
theme	Theme to use instead of the current one (pyzed.theme.current()).

toggle_group

toggle_group(
    options,
    selected,
    on_select=None,
    *,
    disabled=False,
    multiple=False,
    theme=None,
)

An icon-only segmented control.

Parameter	Description
options	(value, icon_name) or (value, icon_name, tooltip).
selected	Current value (a collection with multiple).
on_select	Callable that receives the chosen item.
disabled	True, or the values to disable.
multiple	Each button toggles its value on or off.
theme	Theme to use instead of the current one (pyzed.theme.current()).

chip

chip(
    content,
    *,
    on_press=None,
    on_remove=None,
    selected=False,
    icon=None,
    tint='accent',
    disabled=False,
    theme=None,
)

A compact tag, optionally clickable (filters) and with a button to remove it.

Parameter	Description
content	Text.
on_press	Message or callable sent on press. None disables the control.
on_remove	Shows a ✕ that sends this when clicked.
selected	Marks it as selected.
icon	Name of a Lucide icon (pyzed icons lists them).
tint	Color when selected (a theme token).
disabled	Greys it out and ignores presses.
theme	Theme to use instead of the current one (pyzed.theme.current()).

disclosure

disclosure(title, content, *, open, on_toggle=None, end=None, theme=None)

A collapsible section: a header with an arrow that shows or hides content. You own the open state: change it in on_toggle.

Parameter	Description
title	Title (text or widget).
content	Content.
open	Whether it is open.
on_toggle	Message or callable when the header is clicked.
end	Widgets at the end (right).
theme	Theme to use instead of the current one (pyzed.theme.current()).

AccordionSection

class AccordionSection

One section of ui.accordion: key, title, content and optional icon and header end widget.

Parameter	Description
key	Key that identifies the subscription (defaults to the message or the function).
title	Title.
content	Content: a Widget, a string or a number (converted to text).
icon	Name of a Lucide icon (pyzed icons lists them).
end	Widgets at the end (right).

accordion

accordion(
    sections,
    *,
    open=(),
    on_toggle=None,
    icons=None,
    spacing=8,
    padding=(6, 12, 10, 12),
    theme=None,
)

Stacked collapsible sections separated by dividers, like the panels of a settings screen. Each header spans the whole width, so the content lines up with the rest of the panel. You own the open state: change it in on_toggle.

Parameter	Description
sections	ui.AccordionSection(key, title, content, icon=None, end=None) items (or (key, title, content) tuples).
open	The set of open ids, a {id: bool} dict, or True for all.
on_toggle	Called with the key of the clicked header.
icons	{id: icon}: a Lucide icon for each header.
spacing	Space around the dividers between sections.
padding	Padding around the content of an open section.
theme	Theme to use instead of the current one (pyzed.theme.current()).

ui.accordion([
    ui.AccordionSection("layout", "Layout", layout_rows, icon="ruler"),
    ui.AccordionSection("events", "Events", event_rows, icon="zap"),
], open=self.open_sections, on_toggle=lambda key: self.open_sections.symmetric_difference_update({key}))

Console, errors and help

Log

class Log

The entries of a ui.console: thread-safe, capped at limit, with repeated lines folded into one. write(level, text) adds a line; capture() (or with log:) copies print output and tracebacks into it; pipe(stream) reads a subprocess’s output in a background thread; text() returns everything for copying (text(ids) only those lines). write also takes the line’s source, detail (a traceback) and origin ((path, line)) and returns the entry; find(id) looks one up.

Parameter	Description
limit	Most entries kept.
on_write	Called after every write (from any thread).

log = ui.Log()
with log:
    print("hello")          # still reaches the terminal
ui.console(log.entries, on_clear=log.clear)

Methods and properties

Log.write

Log.write(level, text, *, source='', detail='', origin=None)

Adds a line at level (from source, with detail and origin), calls on_write and returns the entry.

Log.find

Log.find(entry_id)

The entry numbered entry_id, or None when it is gone.

Log.clear

Log.clear()

Removes every entry.

Log.counts

Log.counts()

Returns how many lines there are per level, counting folded repeats.

Log.text

Log.text(ids=None)

Everything (or the entries numbered ids) as plain text, for copying.

Log.capturing

Log.capturing  # property

Whether sys.stdout/sys.stderr are being copied into the log.

Log.capture

Log.capture()

Copies sys.stdout/sys.stderr into the log (they still reach the terminal).

Log.release

Log.release()

Stops capturing and puts the original streams back.

Log.pipe

Log.pipe(stream, level='stdout', on_end=None)

Reads a subprocess pipe (bytes or text) line by line into the log, in a background thread.

LogEntry

@dataclass
class LogEntry(level, text, time=time.time(), count=1, source='', detail='', origin=None, id=0)

One line of a ui.Log: level, text, time, count (identical lines in a row), source, detail, origin, its number id, clock (HH:MM:SS) and line() (the entry as plain text).

Parameter	Description
level	Level name.
text	The line.
time	When it was written (time.time()).
count	Identical lines in a row.
source	What it comes from ("project", "agent"…); ui.console can show and filter it.
detail	More text shown under the line while it is selected (a traceback).
origin	(path, line) of the code it is about.
id	Its number in the log (what a ui.LogSelection keeps).

Methods and properties

LogEntry.clock

LogEntry.clock  # property

The entry’s local time as HH:MM:SS.

LogEntry.line

LogEntry.line(*, details=True)

The entry as one line of plain text (its time, level and source, then detail below it).

LogSelection

class LogSelection

The selected lines of a ui.console, like in a file list: a click selects one line, Shift+click a range from the last one clicked and Ctrl+click (Cmd on macOS) adds or removes one. Keep one in your app and pass it to ui.console(selection=...); select(ids) selects exactly those (Ctrl+A), clear() none, keep(entries) forgets lines that are gone, and ids are the selected entries’ ids for log.text(ids).

self.selection = ui.LogSelection()
...
ui.console(self.log.entries, selection=self.selection, on_context=self.open_menu)
# Ctrl+C in on_key:
return pz.Command.copy(self.log.text(self.selection.ids))

Methods and properties

LogSelection.click

LogSelection.click(entry_id, shown, *, shift=False, ctrl=False)

Selects after a click on line entry_id; shown are the ids of the lines on screen, in order.

LogSelection.select

LogSelection.select(ids)

Selects exactly ids (all the lines shown, for Ctrl+A).

LogSelection.clear

LogSelection.clear()

Selects nothing.

LogSelection.keep

LogSelection.keep(entries)

Forgets selected lines that are no longer in entries (cleared or dropped).

LOG_LEVELS

LOG_LEVELS(...)

The levels ui.console colors, in the order of its filter buttons: debug, info, event, stdout, stderr, warning, error.

console

console(
    entries,
    *,
    query='',
    on_query=None,
    hidden=(),
    on_toggle_level=None,
    on_clear=None,
    on_copy=None,
    actions=(),
    selection=None,
    on_context=None,
    on_open=None,
    sources=(),
    source=None,
    on_source=None,
    show_source=False,
    placeholder=None,
    empty=None,
    font_size=12.5,
    id=None,
    theme=None,
)

A log view like a browser’s dev tools console: a filter box, one toggle per level with its count, copy and clear, and the entries in a monospace list that keeps scrolling to the newest one.

Parameter	Description
entries	ui.LogEntry items (log.entries).
query	Filter text.
on_query	Receives each edit of the filter.
hidden	Levels not shown.
on_toggle_level	Called with the level of the clicked toggle.
on_clear	Adds a Clear button.
on_copy	Adds a Copy button.
actions	Extra widgets at the end of the toolbar.
selection	A ui.LogSelection: the lines can be selected with the mouse, and a selected line with detail shows it below.
on_context	Called with the line right-clicked (None under the lines): open a menu there (copy, go to source, clear…).
on_open	Called with the line double-clicked.
sources	(value, label) pairs: adds a dropdown that shows the lines of one source.
source	The source shown (None for all).
on_source	Receives the source picked in the dropdown (None for all).
show_source	Tags each line with its source.
placeholder	Text of the empty filter box.
empty	What shows while there are no lines.
font_size	Size of the entries.
id	Scrollable id.
theme	Theme to use instead of the current one (pyzed.theme.current()).

ErrorInfo

@dataclass
class ErrorInfo(kind, message, traceback='', origin=None, where='', time=0.0)

An error as ui.error_card and ui.error_dialog show it: kind (the exception’s type), message, the whole traceback, the origin (path, line) it comes from (the last frame outside the standard library, installed packages and Pyzed), where it happened and time. ErrorInfo.from_exception(err, where=...) makes one (prefer= picks which frames may be the origin); ErrorInfo.current() describes the exception being handled. summary is Type: message, location is file.py:12 and report() is everything as text for a bug report.

Parameter	Description
kind	The exception’s type name.
message	Its message.
traceback	The whole traceback, as Python prints it.
origin	(path, line) of the code it comes from, or None.
where	What was running.
time	When it happened (time.time()).

try:
    save(data)
except Exception as err:
    self.error = ui.ErrorInfo.from_exception(err, where="Save")

Methods and properties

ErrorInfo.from_exception

@classmethod
ErrorInfo.from_exception(err, *, where='', prefer=None)

Describes err. prefer(path) picks the frames that may be its origin (the last of them wins); by default, those outside the standard library, installed packages and Pyzed itself.

ErrorInfo.current

@classmethod
ErrorInfo.current(*, where='')

The exception being handled (inside an except block), or None.

ErrorInfo.summary

ErrorInfo.summary  # property

Type: message (just the type when the message is empty).

ErrorInfo.location

ErrorInfo.location  # property

file.py:12 for the origin, or "".

ErrorInfo.report

ErrorInfo.report()

Everything as plain text, to copy into a bug report.

error_boundary

error_boundary(
    build,
    *,
    on_error=None,
    title=None,
    where='',
    on_details=None,
    fallback=None,
    theme=None,
)

Draws build(), or an error card when it raises, so one part of the view that fails never takes the whole window down (like React’s error boundaries). on_error(info) is told about the error each time the part is drawn and fails, so report it once (compare info.traceback).

Parameter	Description
build	A function that returns the part’s widget.
on_error	Receives the ui.ErrorInfo.
title	Heading of the card (and the error’s where).
where	What the part is, for the report.
on_details	Adds a Details button; receives the ui.ErrorInfo (open a ui.error_dialog).
fallback	Your own widget for the error: fallback(info).
theme	Theme override.

sidebar = ui.error_boundary(lambda: self.sidebar(), on_error=self.report, title="Sidebar",
                            on_details=self.show_error)

error_card

error_card(info, *, title=None, on_details=None, actions=(), theme=None)

The card ui.error_boundary draws in place of what failed: the error, where it comes from and a Copy error button (and Details with on_details).

Parameter	Description
info	A ui.ErrorInfo.
title	Heading.
on_details	Adds a Details button.
actions	More buttons after them.
theme	Theme override.

error_dialog

error_dialog(
    info,
    on_close,
    *,
    title=None,
    on_go_to=None,
    go_to_label=None,
    on_logs=None,
    more=0,
    width=680,
    theme=None,
)

A dialog with an error: its message, where it happened, the file and line it comes from and the traceback in a read-only editor (select and copy any part), with buttons to copy everything, go to the origin, see it among the logs and close. Show it with ui.dialog_layer or ui.layer.

Parameter	Description
info	A ui.ErrorInfo.
on_close	Close button and Escape.
title	Heading (“Something went wrong”).
on_go_to	Adds the go-to button (open the file at the line).
go_to_label	Its text (“Go to source”).
on_logs	Adds a Show in Logs button.
more	How many other errors came after it (a line says so).
width	Width in pixels or a modal size.
theme	Theme override.

dialog = ui.error_dialog(self.error, self.close_error, on_go_to=self.open_origin) if self.error else None
return ui.dialog_layer(self.main_view(), dialog, on_dismiss=self.close_error)

shortcuts

shortcuts(groups, *, query='', on_query=None, height=380, theme=None)

A searchable list of key bindings, grouped (for a Keyboard shortcuts dialog).

Parameter	Description
groups	[(title, [(label, keys), ...]), ...], keys like "ctrl-s".
query	Filter text.
on_query	Adds a search box.
height	Height of the list.
theme	Theme to use instead of the current one (pyzed.theme.current()).

about

about(
    name,
    version='',
    description='',
    *,
    icon='app-window',
    details=(),
    links=(),
    theme=None,
)

An About box: icon, name, version, a description, a few details and link buttons.

Parameter	Description
name	App name.
version	Version text.
description	One or two sentences.
icon	Lucide icon.
details	(label, value) rows.
links	(label, on_press) buttons.
theme	Theme to use instead of the current one (pyzed.theme.current()).

Data and feedback

callout

callout(
    title,
    description=None,
    *,
    tint='info',
    icon=None,
    actions=(),
    on_dismiss=None,
    theme=None,
)

An inline notice (a callout or banner).

Parameter	Description
title	Title (text or widget).
description	Secondary text.
tint	"info", "success", "warning", "error" or "hint": picks the color and icon.
icon	Name of a Lucide icon (pyzed icons lists them).
actions	Extra widgets (usually buttons) shown as actions.
on_dismiss	Adds a close button.
theme	Theme to use instead of the current one (pyzed.theme.current()).

empty_state

empty_state(
    title,
    description=None,
    *,
    icon='inbox',
    actions=(),
    size='md',
    height='fill',
    theme=None,
)

A centered placeholder for empty lists, searches with no results, etc.

Parameter	Description
title	Title.
description	Secondary text.
icon	Name of a Lucide icon (pyzed icons lists them).
actions	Extra widgets (usually buttons) shown as actions.
size	"sm", "md" or "lg".
height	"fill" (default), pixels or "shrink".
theme	Theme to use instead of the current one (pyzed.theme.current()).

settings_group

settings_group(title, rows, *, description=None, end=None, theme=None)

A titled block of ui.field rows separated by lines, like a settings screen.

Parameter	Description
title	Group title.
rows	The rows (usually ui.field).
description	Secondary text.
end	Widget at the right of the title (a Reset button…).
theme	Theme to use instead of the current one (pyzed.theme.current()).

Column

@dataclass
class Column(title, key, width='fill', align='start', render=None, sortable=True)

A column of ui.table. key is a dict key, an attribute name or a function of the row; render (optional) turns the value into a widget. width is "fill", a number or a portion such as "fill:2".

Parameter	Description
title	Header (and name used for sorting).
key	How to get the value from each row.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
align	"start", "center" or "end".
render	Function value → widget.
sortable	Whether the header can be clicked to sort.

Methods and properties

Column.value

Column.value(row)

Returns this column’s value for row: key(row), a dict item or an attribute.

table

table(
    columns,
    rows,
    *,
    sort_by=None,
    descending=False,
    on_sort=None,
    on_row_press=None,
    selected=None,
    striped=False,
    row_height=30,
    height=None,
    on_row_double_press=None,
    on_row_context=None,
    empty=None,
    theme=None,
)

A data table with a fixed header, optional sorting and row selection. Sorting happens here when sort_by names a column: clicking a header calls on_sort(title) and you update sort_by/descending in your state. Rows are virtualized: only the ones in view are built, so hundreds of thousands of rows scroll smoothly.

Parameter	Description
columns	ui.Column or plain keys.
rows	Dicts or objects.
sort_by	Title of the column to sort by.
descending	Descending order.
on_sort	Callable that receives the clicked title.
on_row_press	Callable that receives the clicked row.
selected	The row to highlight, or a list or set of rows (multiple selection).
striped	Shaded alternating rows.
row_height	Height of each row.
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
on_row_double_press	Called with the row on a double click (open, edit…).
on_row_context	Called with the row on a right click (a context menu).
empty	Text or widget shown in place of the rows when there are none.
theme	Theme to use instead of the current one (pyzed.theme.current()).

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.

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

sparkline

sparkline(values, *, width=120, height=32, tint='accent', fill=True, theme=None)

A tiny line chart for trends.

Parameter	Description
values	Values.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
tint	Semantic color: "accent", "error", "warning", "success", "info" or a token.
fill	Fills the area under the line.
theme	Theme to use instead of the current one (pyzed.theme.current()).

bar_chart

bar_chart(values, *, labels=None, width=320, height=160, tint='accent', theme=None)

A vertical bar chart with optional labels.

Parameter	Description
values	Values.
labels	Labels under each bar.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
tint	Semantic color: "accent", "error", "warning", "success", "info" or a token.
theme	Theme to use instead of the current one (pyzed.theme.current()).

donut

donut(values, *, colors=None, size=96, thickness=14, label=None, theme=None)

A donut chart; label is drawn in the center.

Parameter	Description
values	Values.
colors	Colors (defaults to the theme’s).
size	Size.
thickness	Ring thickness.
label	Center text.
theme	Theme to use instead of the current one (pyzed.theme.current()).

spinner

spinner(*, size=16, tint='accent', speed=1.0, theme=None)

A spinning arc for loading states. Its angle comes from the clock, so keep a pz.every(1/30, ...) subscription active while it is shown.

Parameter	Description
size	Size.
tint	Semantic color: "accent", "error", "warning", "success", "info" or a token.
speed	Turns per second.
theme	Theme to use instead of the current one (pyzed.theme.current()).

count_badge

count_badge(count, *, tint='accent', max=99, show_zero=True, theme=None)

A round counter (notifications, problems…). Shows 99+ above max.

Parameter	Description
count	The number.
tint	Semantic color: "accent", "error", "warning", "success", "info" or a token.
max	Maximum before showing N+.
show_zero	With False, a count of 0 draws nothing.
theme	Theme to use instead of the current one (pyzed.theme.current()).

facepile

facepile(people, *, size=22, overlap=6, max_shown=5, theme=None)

Overlapping collaborator avatars, as in the title bar of a collaborative editor. Those beyond max_shown are grouped into +N.

Parameter	Description
people	Initials or names.
size	Size.
overlap	Overlap in pixels.
max_shown	How many to show.
theme	Theme to use instead of the current one (pyzed.theme.current()).

diff_stat

diff_stat(added, removed, *, blocks=5, theme=None)

+12 −3 with GitHub-style colored blocks.

Parameter	Description
added	Lines added.
removed	Lines removed.
blocks	Number of blocks.
theme	Theme to use instead of the current one (pyzed.theme.current()).

keybinding_hint

keybinding_hint(text, keys, *, theme=None)

A muted hint like “Open file Ctrl P” for footers and empty states.

Parameter	Description
text	Text.
keys	Shortcut shown at the end, written as a string: "ctrl-s", "cmd-k cmd-s".
theme	Theme to use instead of the current one (pyzed.theme.current()).

markdown

markdown(source, *, size=None, on_link=None, width=None, selectable=None, theme=None)

pz.markdown with the theme’s text, link and code colors.

Parameter	Description
source	The Markdown text.
size	Size.
on_link	Callable that receives the URL when a link is clicked.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
selectable	Same as in pz.markdown; the selection uses the theme’s selection color.
theme	Theme to use instead of the current one (pyzed.theme.current()).

split

split(
    first,
    second,
    *,
    ratio=0.5,
    on_resize=None,
    vertical=False,
    min_size=80,
    theme=None,
    **kwargs,
)

pz.split with the divider in the theme’s border color (accent while dragging).

Parameter	Description
first	First pane.
second	Second pane.
ratio	Proportion of the first pane (0–1).
on_resize	Callable that receives the new ratio.
vertical	Vertical orientation.
min_size	Minimum size of each pane.
theme	Theme to use instead of the current one (pyzed.theme.current()).
kwargs	Same as pz.split.

Lists, tree and menus

list_item

list_item(
    content,
    on_press=None,
    *,
    icon=None,
    icon_color=None,
    start=None,
    end=None,
    selected=False,
    focused=False,
    indent=0,
    height=26,
    color=None,
    inset=False,
    disabled=False,
    on_right_press=None,
    on_double_press=None,
    description=None,
    tooltip=None,
    theme=None,
)

A list row: icon, text and a slot at the end.

Parameter	Description
content	Text or widget.
on_press	Message or callable sent on press. None disables the control.
icon	Name of a Lucide icon (pyzed icons lists them).
icon_color	Icon color: a theme token or a hex color.
start	Widgets at the start (left).
end	Widgets at the end (right).
selected	Marks it as selected.
focused	Draws a focus border.
indent	Left indentation, in pixels.
height	Row height.
color	Text color.
inset	With margin and rounded corners (menus, palettes).
disabled	Disables it (ignores clicks).
on_right_press	Right click.
on_double_press	Sent on a double click (open, rename…).
description	A muted second line (the row grows to 40 px unless height is set).
tooltip	Text shown on hover.
theme	Theme to use instead of the current one (pyzed.theme.current()).

list_header

list_header(title, *, end=None, theme=None)

A section header for lists.

Parameter	Description
title	Title.
end	Widgets at the end (right).
theme	Theme to use instead of the current one (pyzed.theme.current()).

TreeNode

@dataclass
class TreeNode(name, children=None, id=None, status=None, icon=None, icon_color=None)

A file or folder for ui.tree. Folders have children (a list). status is "modified", "created", "deleted", "conflict" or "ignored". TreeNode.from_paths(paths, status=None) builds the tree from paths like "src/main.rs", with folders first and the git status propagated to folders.

Parameter	Description
name	Display name.
children	Children (None for a file).
id	Stable identifier used to focus or scroll it with a Command.
status	Git status.
icon	Name of a Lucide icon (pyzed icons lists them).
icon_color	Icon color: a theme token or a hex color.

Methods and properties

TreeNode.is_folder

TreeNode.is_folder  # property

Whether the node is a folder (it has a children list, even if empty).

TreeNode.from_paths

@classmethod
TreeNode.from_paths(paths, status=None)

Builds a tree from "src/main.rs"-style paths. Folders sort first.

TreeNode.sort

TreeNode.sort()

Sorts the children recursively: folders first, then by name ignoring case.

tree

tree(
    nodes,
    *,
    expanded,
    selected=None,
    on_toggle=None,
    on_select=None,
    on_open=None,
    on_context=None,
    focused=None,
    indent=14,
    item_height=24,
    theme=None,
)

A collapsible file tree, like a code editor’s project panel.

Parameter	Description
nodes	List of TreeNode.
expanded	Set of open folder ids.
selected	One id or a collection of ids (multiple selection).
on_toggle	Called with the id of the clicked folder.
on_select	Called with the id of the clicked file.
on_open	Called with the id of a file that is double-clicked.
on_context	Called with the id of a row that is right-clicked (show a ui.menu there).
focused	Outlines the row the keyboard is on.
indent	Left indentation, in pixels.
item_height	Height of each row.
theme	Theme to use instead of the current one (pyzed.theme.current()).

MenuItem

@dataclass
class MenuItem(label, on_press=None, icon=None, keys=None, disabled=False, danger=False, checked=None, description=None, submenu=False)

An entry of ui.menu.

Parameter	Description
label	Label text.
on_press	Message or callable sent on press. None disables the control.
icon	Name of a Lucide icon (pyzed icons lists them).
keys	Shortcut shown at the end, written as a string: "ctrl-s", "cmd-k cmd-s".
disabled	Disables it (ignores clicks).
danger	In red (destructive actions).
checked	Shows a check mark (True/False) or nothing (None).
description	A muted second line.
submenu	Ends the row with a chevron; open the next menu beside it in on_press.

menu

menu(items, *, width=240, max_height=None, theme=None)

A floating context menu. Use ui.SEPARATOR between groups; a plain string is a header.

Parameter	Description
items	List of MenuItem, ui.SEPARATOR or strings.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
max_height	Scrolls a menu taller than this.
theme	Theme to use instead of the current one (pyzed.theme.current()).

SEPARATOR

Separator for ui.menu.

virtual_list

virtual_list(
    items,
    render,
    *,
    item_height=26,
    spacing=0,
    width='fill',
    height='fill',
    padding=None,
    overscan=4,
    id=None,
    on_scroll=None,
    theme=None,
)

A scrolling list that only builds the rows in view, for thousands or millions of items. render(item) returns the widget for one item and is called when it scrolls into view. Every row has the same height.

Parameter	Description
items	The items: a list or any sequence (other iterables are turned into a list).
render	Function that receives an item and returns its widget.
item_height	Height of every row, in pixels.
spacing	Space between children, in pixels.
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).
overscan	Extra rows built above and below the visible ones.
id	Stable identifier used to focus or scroll it with a Command.
on_scroll	Callable that receives the scroll viewport, as in pz.scrollable.
theme	Theme to use instead of the current one (pyzed.theme.current()).

Navigation

Tab

@dataclass
class Tab(id, label, icon=None, icon_color=None, dirty=False, preview=False, status=None, pinned=False, tooltip=None)

A tab. Tab.for_file(path, **kwargs) creates it with the file’s name and icon.

Parameter	Description
id	Stable identifier used to focus or scroll it with a Command.
label	Label text.
icon	Name of a Lucide icon (pyzed icons lists them).
icon_color	Icon color: a theme token or a hex color.
dirty	Unsaved changes (shows a dot).
preview	Preview tab (in italics).
status	Git status (tints the name).
pinned	Shows only the icon, has no close button and goes first in tab_bar.
tooltip	Text shown on hover (the full path…).

Methods and properties

Tab.for_file

@classmethod
Tab.for_file(path, **kwargs)

A tab for a file path: its name as label and the matching file icon and color.

tab

tab(item, *, active, on_select=None, on_close=None, height=32, dimmed=False, theme=None)

A single tab. You normally use tab_bar.

Parameter	Description
item	The Tab.
active	Whether it is the active one.
on_select	Callable that receives the chosen item.
on_close	Message or callable sent when the X is pressed.
height	Height.
dimmed	Mutes the label (the tab being dragged).
theme	Theme to use instead of the current one (pyzed.theme.current()).

tab_bar

tab_bar(
    tabs,
    active,
    *,
    on_select=None,
    on_close=None,
    start=(),
    end=(),
    height=32,
    on_drag=None,
    on_drop=None,
    on_drag_over=None,
    dragging=None,
    drop_index=None,
    on_context=None,
    on_new=None,
    theme=None,
)

A row of tabs with optional controls at the start and end (navigation, split, +). The close button appears on the active tab and on hover. Tabs can be dragged to reorder them or out of the window: see Draggable tabs.

Parameter	Description
tabs	List of Tab.
active	Id of the active tab.
on_select	Callable that receives the chosen item.
on_close	Message or callable sent when the X is pressed.
start	Widgets at the start (left).
end	Widgets at the end (right).
height	Height.
on_drag	Called with the tab id when a tab starts being dragged.
on_drop	Called with the tab id and the Event when the dragged tab is released: event.window_x/window_y (outside the window if it was dropped outside) and event.screen.
on_drag_over	While dragging is set: called with the insertion index under the pointer, or None when it leaves the bar.
dragging	Id of the tab being dragged (dims it and turns on on_drag_over).
drop_index	Draws the insertion mark before the tab at this index (len(tabs): after the last one).
on_context	Called with the id of a tab that is right-clicked.
on_new	Sent on a double click of the empty space after the tabs.
theme	Theme to use instead of the current one (pyzed.theme.current()).

breadcrumbs

breadcrumbs(
    parts,
    *,
    separator='›',
    on_press=None,
    max_items=None,
    on_more=None,
    theme=None,
)

src › main.rs › fn main. Parts can be strings or (icon, text) tuples.

Parameter	Description
parts	The parts.
separator	Separator.
on_press	Called with the index of the clicked part.
max_items	Keeps the first part and the last ones and shows … for the rest.
on_more	Makes the … clickable.
theme	Theme to use instead of the current one (pyzed.theme.current()).

toolbar

toolbar(start=(), end=(), *, center=None, height=32, theme=None)

The bar below the tabs: breadcrumbs on the left and buffer actions on the right.

Parameter	Description
start	Widgets at the start (left).
end	Widgets at the end (right).
center	Kept in the middle of the bar whatever the widths of both sides.
height	Height.
theme	Theme to use instead of the current one (pyzed.theme.current()).

Workspace

workspace

workspace(
    center,
    *,
    title_bar=None,
    left=None,
    right=None,
    bottom=None,
    status_bar=None,
    left_width=240,
    right_width=320,
    bottom_height=220,
    on_resize=None,
    theme=None,
)

The layout of an editor-style window: title bar, left, right and bottom docks, center and status bar. Pass None to hide a dock.

Parameter	Description
center	Central content (usually tabs + editor).
title_bar	Title bar (ui.title_bar).
left	Left dock.
right	Right dock.
bottom	Bottom dock.
status_bar	Status bar (ui.status_bar).
left_width	Width of the left dock.
right_width	Width of the right dock.
bottom_height	Height of the bottom dock.
on_resize	Called with (side, size) when the user finishes resizing a dock by dragging its inner border.
theme	Theme to use instead of the current one (pyzed.theme.current()).

title_bar

title_bar(start=(), end=(), *, center=None, height=34, theme=None)

The top bar: project and branch pickers on the left, account and actions on the right.

Parameter	Description
start	Widgets at the start (left).
end	Widgets at the end (right).
center	Centered widget.
height	Height.
theme	Theme to use instead of the current one (pyzed.theme.current()).

title_button

title_button(
    content,
    on_press=None,
    *,
    icon=None,
    muted=False,
    chevron=False,
    theme=None,
)

A compact button for the title bar (pyzed ▾, main…).

Parameter	Description
content	Text.
on_press	Message or callable sent on press. None disables the control.
icon	Name of a Lucide icon (pyzed icons lists them).
muted	Muted text.
chevron	Adds a ▾.
theme	Theme to use instead of the current one (pyzed.theme.current()).

status_bar

status_bar(start=(), end=(), *, height=28, theme=None)

The bottom status bar.

Parameter	Description
start	Widgets at the start (left).
end	Widgets at the end (right).
height	Height.
theme	Theme to use instead of the current one (pyzed.theme.current()).

status_item

status_item(
    content=None,
    on_press=None,
    *,
    icon=None,
    color=None,
    icon_color=None,
    selected=False,
    tooltip=None,
    keys=None,
    theme=None,
)

An icon and/or text in the status bar (diagnostics, cursor position, language…).

Parameter	Description
content	Text.
on_press	Message or callable sent on press. None disables the control.
icon	Name of a Lucide icon (pyzed icons lists them).
color	Text or icon color.
icon_color	Icon color: a theme token or a hex color.
selected	Marks it as selected.
tooltip	Tooltip text.
keys	Shortcut shown at the end, written as a string: "ctrl-s", "cmd-k cmd-s".
theme	Theme to use instead of the current one (pyzed.theme.current()).

panel

panel(
    content,
    *,
    header=None,
    width=None,
    height=None,
    side='left',
    resizable=True,
    on_resize=None,
    min_size=120,
    theme=None,
)

A dockable panel. side decides which edge gets the border line; with a numeric width (height for the bottom) that border can be dragged to resize it.

Parameter	Description
content	Content: a Widget, a string or a number (converted to text).
header	Header (ui.panel_header).
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
side	"left", "right" or "bottom".
resizable	False keeps the size fixed.
on_resize	Called with the new size when a drag ends.
min_size	Smallest size when resizing.
theme	Theme to use instead of the current one (pyzed.theme.current()).

panel_header

panel_header(title, actions=(), *, icon=None, height=32, theme=None)

A panel header: icon, title and actions.

Parameter	Description
title	Title.
actions	Extra widgets (usually buttons) shown as actions.
icon	Name of a Lucide icon (pyzed icons lists them).
height	Height.
theme	Theme to use instead of the current one (pyzed.theme.current()).

Window frame

window_frame

window_frame(
    content,
    *,
    title=None,
    menus=None,
    menu_button=True,
    start=(),
    center=None,
    end=(),
    style=None,
    window=None,
    height=None,
    resize_border=6.0,
    resize_edges=True,
    bg=None,
    theme=None,
)

The whole frame of a window opened with frame="custom": a title bar that moves the window (double click maximizes, right click opens the system menu on Windows), the minimize, maximize and close buttons in the style of a platform, menus on the left, and borders that resize the window.

Parameter	Description
content	The window’s content, under the title bar.
title	Title shown in the bar. By default the window’s title.
menus	Menus on the left of the bar: a list of ui.Menu.
menu_button	Shows the menus behind a ☰ button (False always shows their names).
start	Items after the menus (project, branch…).
center	Your own widget in the middle instead of the title (a search field, Run and Stop…); the bar still drags on both sides of it.
end	Items before the window buttons.
style	"macos", "windows", "gnome", "ubuntu" or "kde". By default the window’s frame, or this system’s.
window	The window the buttons act on. By default the one whose view() is running.
height	Height of the bar. By default the platform’s.
resize_border	Width in pixels of the borders that resize the window.
resize_edges	False leaves the resize borders to you (pz.window_edges), to put them over menus and dialogs.
bg	Background color ("#rrggbb[aa]", (r, g, b[, a]) or "transparent").
theme	Theme to use instead of the current one (pyzed.theme.current()).

class Notes(pz.App):
frame = "custom"

def view(self):
    return ui.window_frame(self.editor(), menus=[ui.Menu("File", [ui.MenuItem("Open", self.open)])],
                           end=[ui.icon_button("settings", self.settings)])

window_title_bar

window_title_bar(
    title=None,
    *,
    style=None,
    start=(),
    center=None,
    end=(),
    on_drag=None,
    on_minimize=None,
    on_maximize=None,
    on_close=None,
    on_menu=None,
    maximized=False,
    focused=True,
    width='fill',
    height=None,
    bg=None,
    border=True,
    theme=None,
)

A window’s title bar alone: window buttons in the style of style (on the left for macOS), start items, the title and end items. Without callbacks it only shows, which is how Pyzed Design previews a form in the frame of each platform.

Parameter	Description
title	Title (centered, or on the left on Windows).
style	"macos", "windows", "gnome", "ubuntu" or "kde" (None: this system’s).
start	Items at the start.
center	Widget in the middle instead of the title; the bar still drags on both sides of it.
end	Items at the end.
on_drag	Called when the empty part of the bar is dragged (return Command.drag_window()).
on_minimize	Minimize button.
on_maximize	Maximize button and double click on the bar.
on_close	Close button.
on_menu	Right click on the bar.
maximized	Shows the restore symbol.
focused	False dims it like a window in the background.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
height	Height. By default the platform’s.
bg	Background color ("#rrggbb[aa]", (r, g, b[, a]) or "transparent").
border	Line under the bar.
theme	Theme to use instead of the current one (pyzed.theme.current()).

window_controls

window_controls(
    style=None,
    *,
    on_minimize=None,
    on_maximize=None,
    on_close=None,
    maximized=False,
    focused=True,
    height=None,
    theme=None,
)

The minimize, maximize and close buttons in the style of a platform. A button without a callback is drawn but does nothing.

Parameter	Description
style	"macos", "windows", "gnome", "ubuntu" or "kde" (None: this system’s).
on_minimize	Minimize button.
on_maximize	Maximize button.
on_close	Close button.
maximized	Shows the restore symbol.
focused	False dims them.
height	Height.
theme	Theme to use instead of the current one (pyzed.theme.current()).

Menu

@dataclass
class Menu(label, items=[])

A menu of a window frame’s menu bar: a name and its items (ui.MenuItem, ui.SEPARATOR or a header string).

Parameter	Description
label	The menu’s name.
items	Its entries: ui.MenuItem, ui.SEPARATOR or a header string.

ui.Menu("File", [ui.MenuItem("Open…", self.open, keys="ctrl-o"), ui.SEPARATOR, ui.MenuItem("Quit", self.close)])

system_platform

system_platform()

The style of this system’s window buttons: "macos", "windows", "kde", "ubuntu" or "gnome" (other Linux desktops). Under WSL it is "windows".

Overlays

layer

layer(
    base,
    overlay=None,
    *,
    on_dismiss=None,
    backdrop=None,
    align_x='center',
    align_y='start',
    offset=72,
)

Stacks overlay on top of base. Clicking outside sends on_dismiss. With overlay=None it returns base unchanged.

Parameter	Description
base	The UI underneath.
overlay	What floats on top (modal, palette, menu).
on_dismiss	Message or callable sent on close.
backdrop	Color of the backdrop that dims the UI.
align_x	Horizontal alignment: "start"/"left", "center", "end"/"right".
align_y	Vertical alignment: "start"/"top", "center", "end"/"bottom".
offset	Distance from the top when align_y is "start".

modal

modal(
    content,
    *,
    title=None,
    on_close=None,
    width=480,
    footer=(),
    description=None,
    icon=None,
    max_height=None,
    theme=None,
)

A dialog. Use it as the overlay of ui.layer.

Parameter	Description
content	Content: a Widget, a string or a number (converted to text).
title	Title.
on_close	The close button; also sent by Escape while the dialog has focus.
width	Pixels or "sm" (360), "md" (480), "lg" (640) or "xl" (820).
footer	Footer buttons, aligned to the right.
description	Muted line under the title.
icon	Icon before the title.
max_height	Scrolls content taller than this, keeping the header and footer in view.
theme	Theme to use instead of the current one (pyzed.theme.current()).

PaletteItem

@dataclass
class PaletteItem(label, on_press=None, keys=None, icon=None, detail=None)

An entry of command_palette or picker.

Parameter	Description
label	Label text.
on_press	Message or callable sent on press. None disables the control.
keys	Shortcut shown at the end, written as a string: "ctrl-s", "cmd-k cmd-s".
icon	Name of a Lucide icon (pyzed icons lists them).
detail	Secondary text (for example, a file path).

command_palette

command_palette(
    query,
    on_query,
    commands,
    *,
    selected=0,
    on_submit=None,
    placeholder='Execute a command…',
    input_id='command-palette',
    theme=None,
    **kwargs,
)

A command palette: fuzzy-filters commands by query and shows their shortcuts.

Parameter	Description
query	Search text.
on_query	Callable that receives the new text.
commands	List of PaletteItem.
selected	Highlighted index (for arrow-key navigation).
on_submit	Message or callable sent when Enter is pressed.
placeholder	Hint text shown when empty.
input_id	Field id (for Command.focus).
theme	Theme to use instead of the current one (pyzed.theme.current()).
kwargs	Same as picker.

picker

picker(
    query,
    on_query,
    items,
    *,
    selected=0,
    placeholder='Search…',
    input_id='picker',
    on_submit=None,
    width=560,
    max_height=340,
    empty_text='No matches',
    theme=None,
)

A searchable list on a floating surface. The basis of the palette and the file finder.

Parameter	Description
query	Search text.
on_query	Callable that receives the new text.
items	(PaletteItem, positions) pairs, for example from fuzzy_filter.
selected	Highlighted index.
placeholder	Hint text shown when empty.
input_id	Field id.
on_submit	Message or callable sent when Enter is pressed.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
max_height	Maximum height in pixels.
empty_text	Text shown when there are no results.
theme	Theme to use instead of the current one (pyzed.theme.current()).

fuzzy_match

fuzzy_match(query, candidate)

Returns (score, positions) if every letter of query appears in order in candidate; otherwise None. Rewards word starts and consecutive letters.

Parameter	Description
query	Search text.
candidate	Candidate text.

fuzzy_filter

fuzzy_filter(query, items, key=<class 'str'>)

Filters and sorts items by fuzzy score. Returns [(item, positions), ...].

Parameter	Description
query	Search text.
items	Items.
key	Function that returns the text of each item.

highlighted

highlighted(text, positions, *, color, match_color, size=13.5, weight=None)

Text with the characters at positions highlighted (fuzzy search matches).

Parameter	Description
text	Text.
positions	Indices to highlight.
color	Text or icon color.
match_color	Color of the matches.
size	Size.
weight	Text weight.

toast

toast(
    title,
    message=None,
    *,
    kind='info',
    icon=None,
    on_dismiss=None,
    actions=(),
    width=340,
    progress=None,
    on_press=None,
    theme=None,
)

A notification.

Parameter	Description
title	Title.
message	Secondary text.
kind	"info", "success", "warning" or "error".
icon	Name of a Lucide icon (pyzed icons lists them).
on_dismiss	Message or callable sent on close.
actions	Extra widgets (usually buttons) shown as actions.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
progress	0 to 1: a thin bar at the bottom (time left, a download).
on_press	Makes the card clickable.
theme	Theme to use instead of the current one (pyzed.theme.current()).

toasts

toasts(base, items, *, spacing=8)

Shows items (usually toast(...)) stacked in the bottom-right corner over base.

Parameter	Description
base	The UI underneath.
items	List of toasts.
spacing	Space between children, in pixels.

popover

popover(base, content=None, *, x=0, y=0, on_dismiss=None, align_x='start')

Shows content (a ui.menu, a card…) over base at (x, y). Clicking anywhere else calls on_dismiss. For a right-click menu, store the mouse position with mouse_area(on_move=...) and open the popover from on_right_press (see examples/context_menu.py).

Parameter	Description
base	The UI underneath.
content	What floats (or None).
x	Horizontal position.
y	Vertical position.
on_dismiss	Message or callable sent on close.
align_x	Horizontal alignment: "start"/"left", "center", "end"/"right".

Code

editor

editor(
    id,
    text='',
    *,
    language=None,
    path=None,
    on_change=None,
    on_cursor=None,
    markers=None,
    font_size=None,
    line_height=None,
    gutter=True,
    wrap=False,
    active_line=True,
    height='fill',
    placeholder=None,
    annotations=None,
    show_whitespace=False,
    tab_size=None,
    hard_tabs=False,
    backspace_unindent=True,
    repeat_delay=None,
    repeat_rate=None,
    capture_keys=(),
    on_scroll=None,
    auto_close=True,
    folding=True,
    minimap=False,
    cursor_shape='bar',
    cursor_blink=True,
    cursor_width=2.0,
    cursor_color=None,
    on_zoom=None,
    on_action=None,
    highlights=None,
    match_brackets=True,
    selection_highlight=True,
    font=None,
    keymap=None,
    scrollbar=True,
    readonly=False,
    on_hover=None,
    hover_delay=500,
    sticky_scroll=0,
    theme=None,
)

A code editor: highlighting with the theme colors, line numbers and git markers.

Parameter	Description
id	Identifies the buffer (use the file path).
text	Initial text.
language	Language. If missing, it is inferred from path.
path	File path.
on_change	Callable that receives the new value.
on_cursor	Callable that receives (line, column).
markers	`{line: “created”
font_size	Font size (defaults to the theme’s).
line_height	Line height.
gutter	Shows line numbers.
wrap	Line wrapping.
active_line	Background color of the cursor line.
height	Height: pixels, "fill", "shrink" or "fill:N" (proportion).
placeholder	Hint text shown when empty.
annotations	{line: "text"} or {line: ("text", color)}: virtual text at the end of the line (code lens, diagnostics).
show_whitespace	Draws spaces as · and tabs as →.
tab_size	Tab inserts spaces up to the next multiple; Enter keeps the indentation (one more level after :); Backspace removes a level.
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).
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	Closes brackets and quotes as you type (and wraps the selection).
folding	Fold chevrons in the gutter; Ctrl+Shift+[ folds and Ctrl+Shift+] unfolds.
minimap	True (or a width in pixels) shows a minimap on the right.
cursor_shape	"bar", "block", "underline" or "hollow".
cursor_blink	Whether the cursor blinks.
cursor_width	Width of the bar cursor.
cursor_color	Cursor color (the theme’s player color by default).
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"…), e.g. to count them.
highlights	Ranges painted behind the text in the theme’s search color: [(line, column, end_line, end_column)], from 1, with exclusive ends.
match_brackets	Outlines the bracket that matches the one next to the cursor (Ctrl+M jumps to it).
selection_highlight	Highlights the other occurrences of the selected text (Ctrl+D adds the next one as a cursor).
font	Typeface: "mono" by default; "sans" makes a multi-line text box, like a chat’s message box.
keymap	Zed-style {binding: action} dict ({"ctrl-shift-d": "duplicate_line_down"}); None as the action removes a default key. Build it from per-action overrides with pyzed.ui.editor.keymap_for.
scrollbar	False hides the scrollbars.
readonly	True lets the text be selected and copied but not changed (a log, a traceback).
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).
theme	Theme to use instead of the current one (pyzed.theme.current()).

language_token

language_token(path)

Returns the highlighter language token for a path ("main.rs" → "rs").

Parameter	Description
path	File path.

terminal

terminal(lines, *, font_size=13, id=None, theme=None)

A read-only terminal view with ANSI colors. It stays scrolled to the end.

Parameter	Description
lines	Text with ANSI escapes, or a list of lines of (text, color) segments.
font_size	Font size.
id	Stable identifier used to focus or scroll it with a Command.
theme	Theme to use instead of the current one (pyzed.theme.current()).

ansi

ansi(text)

Converts text with ANSI colors into lines of (text, color_name) segments.

Parameter	Description
text	Text with ANSI escapes.

Color picker

ColorPicker

class ColorPicker

A component that picks a color with alpha, a linear gradient (stops you add, drag and remove, plus an angle) or a fill with an opacity mask. on_change gets a "#rrggbb[aa]" string, a pz.Gradient or a pz.Paint, all valid as a background. Pass the picked value back as value. See Styles.

Parameter	Description
value	A color, theme token, pz.Gradient or pz.Paint.
alpha	Shows the alpha bar and field.
gradients	Shows the Solid/Gradient switch.
masks	Shows the mask editor.
swatches	Quick colors (default: the theme’s accent and status colors).
on_change	Receives event.value.

ui.ColorPicker(value=self.fill, on_change=lambda e: setattr(self, "fill", e.value))

Methods and properties

ColorPicker.parts

ColorPicker.parts()

(stops, angle, mask, opacity): one stop and no angle for a plain color.

ColorPicker.build

ColorPicker.build(stops, angle, mask, opacity)

Turns (stops, angle, mask, opacity) back into a color, Gradient or Paint.

ColorPicker.publish

ColorPicker.publish(*parts)

Sets the value from parts, drops any half-typed hex text and emits change.

ColorPicker.current

ColorPicker.current()

Returns the hex color being edited (the selected stop’s color).

ColorPicker.set_color

ColorPicker.set_color(color)

Replaces the selected stop’s color with color and publishes the result.

ColorPicker.hsva

ColorPicker.hsva()

Returns the edited color as (h, s, v, a), each 0 to 1.

ColorPicker.pick_sv

ColorPicker.pick_sv(event)

Sets saturation and value from a press or drag on the saturation/value area.

ColorPicker.pick_hue

ColorPicker.pick_hue(event)

Sets the hue from a press or drag on the hue bar.

ColorPicker.pick_alpha

ColorPicker.pick_alpha(event)

Sets the alpha from a press or drag on the alpha bar.

ColorPicker.type_hex

ColorPicker.type_hex(text)

Handles typing in the hex field: applies the text once it is a valid hex color.

ColorPicker.set_alpha_percent

ColorPicker.set_alpha_percent(value)

Sets the alpha from the percent field (0 to 100).

ColorPicker.set_mode

ColorPicker.set_mode(mode)

Switches between "Solid" and "Gradient".

ColorPicker.set_angle

ColorPicker.set_angle(value)

Sets the gradient’s angle in degrees (or the mask’s, on a plain color).

ColorPicker.select_stop

ColorPicker.select_stop(index)

Selects the gradient stop at index for editing.

ColorPicker.move_stop

ColorPicker.move_stop(index, event)

Moves a gradient stop to where the bar is pressed or by a drag’s dx.

ColorPicker.add_stop

ColorPicker.add_stop(event)

Adds a gradient stop where the bar is clicked, with the color the gradient has there.

ColorPicker.remove_stop

ColorPicker.remove_stop()

Removes the selected gradient stop (a gradient keeps at least two).

ColorPicker.toggle_mask

ColorPicker.toggle_mask(on)

Adds a mask fading from opaque to transparent when on, or removes the mask.

ColorPicker.select_mask_stop

ColorPicker.select_mask_stop(index)

Selects the mask stop at index for editing.

ColorPicker.move_mask_stop

ColorPicker.move_mask_stop(index, event)

Moves a mask stop to where the bar is pressed or by a drag’s dx, keeping stops sorted.

ColorPicker.add_mask_stop

ColorPicker.add_mask_stop(event)

Adds a mask stop where the bar is clicked, with the opacity the mask has there (at most 8).

ColorPicker.set_mask_opacity

ColorPicker.set_mask_opacity(value)

Sets the selected mask stop’s opacity (0 to 1).

ColorPicker.remove_mask_stop

ColorPicker.remove_mask_stop()

Removes the selected mask stop (a mask keeps at least two).

ColorPicker.marker

ColorPicker.marker(x, y, color, *, size=14, selected=True, **events)

A round handle of color centered on (x, y).

ColorPicker.area

ColorPicker.area(layers, height, markers, on_pick, *, width=248)

A rounded strip of stacked layers that reports where it is pressed and dragged.

ColorPicker.sv_area

ColorPicker.sv_area()

The saturation/value square for the current hue, with a marker on the current color.

ColorPicker.hue_bar

ColorPicker.hue_bar()

The rainbow hue bar with a marker on the current hue.

ColorPicker.alpha_bar

ColorPicker.alpha_bar()

The alpha bar (over a checkerboard) with a marker on the current alpha.

ColorPicker.stops_bar

ColorPicker.stops_bar(points, preview, selected, on_select, on_move, on_add, *, colors=True)

A bar previewing preview with a draggable handle per (offset, value) point.

color_swatch

color_swatch(value, *, size=20, on_press=None)

A small square showing a color, gradient or paint over a checkerboard.

Parameter	Description
value	What to show.
size	Side in pixels.
on_press	Makes it clickable.

checkerboard

checkerboard(width, height, size=6)

A light/dark checkerboard to draw under translucent colors.

Parameter	Description
width	Width.
height	Height.
size	Cell size.

Dates and times

Calendar

class Calendar

A component with a month to pick a day on (mode="single"), a range ("range": the first click starts it, the second ends it) or several days ("multiple"). The title opens a grid of months, then of years. Once clicked it takes the keyboard: arrows move, Enter picks, Page Up/Down change month. See the Calendar page.

Parameter	Description
value	A date (datetime.date or "2026-10-22"), a (start, end) pair or a list of dates, by mode.
mode	"single", "range" or "multiple".
min	The earliest day that can be picked.
max	The latest day that can be picked.
disabled	Days that cannot be picked: dates, weekday names ("sunday") or "weekends".
first_weekday	"monday", "sunday" or "saturday".
months	Months shown side by side.
week_numbers	Shows the ISO week number of each row.
show_outside	Shows the days of the months around.
today_button	Adds a Today link.
on_change	Receives event.value (a date, a tuple or a list).
on_month	Receives event.value, the (year, month) shown.

ui.Calendar(self.day, on_change=lambda e: setattr(self, "day", e.value))
ui.Calendar(self.stay, mode="range", months=2, on_change=lambda e: setattr(self, "stay", e.value))

DatePicker

class DatePicker

A component: a date field that opens a calendar below it, in a popup that panels never cut off. It can be typed in format (Enter or leaving the field reads it); once clicked, ↑/↓ move the date a day and Page Up/Down a month without opening anything, Alt+↓ opens the calendar and Escape closes it. See the Date picker page.

Parameter	Description
value	The date (datetime.date, ISO text or None).
format	How it is written: "DD/MM/YYYY", "MMM D, YYYY"… (see format_date).
placeholder	Hint while empty (default: the format).
min	The earliest date.
max	The latest date.
disabled_dates	Days that cannot be picked (as in Calendar).
first_weekday	"monday", "sunday" or "saturday".
week_numbers	Shows week numbers in the calendar.
clearable	Shows an x that empties it.
today_button	Adds a Today link to the calendar.
disabled	Greys it out.
invalid	Paints the border in the error color.
on_change	Receives event.value: a datetime.date or None.
on_open	The calendar opened.
on_close	The calendar closed.

ui.DatePicker(self.due, format="DD/MM/YYYY", on_change=lambda e: setattr(self, "due", e.value))

DateRangePicker

class DateRangePicker

A component: a field for a start and an end date, with two months and quick ranges (Today, Last 7 days, This month…) in its popup. Typed text is two dates separated by separator. See the Date range picker page.

Parameter	Description
value	(start, end): dates, ISO text or None.
format	How each date is written.
separator	Text between the two dates.
placeholder	Hint while empty.
min	The earliest date.
max	The latest date.
disabled_dates	Days that cannot be picked.
first_weekday	"monday", "sunday" or "saturday".
months	Months shown side by side.
presets	Shows the quick ranges.
clearable	Shows an x that empties it.
disabled	Greys it out.
invalid	Paints the border in the error color.
on_change	Receives event.value: (start, end).
on_open	The calendar opened.
on_close	The calendar closed.

ui.DateRangePicker(self.period, on_change=lambda e: setattr(self, "period", e.value))

TimePicker

class TimePicker

A component: a time field with columns of hours and minutes (and seconds, and AM/PM with a 12-hour format) in a popup. Once clicked, ↑/↓ change it by minute_step. See the Time picker page.

Parameter	Description
value	The time (datetime.time, "14:30" or None).
format	"HH:mm", "HH:mm:ss", "h:mm A"…
placeholder	Hint while empty.
minute_step	Minutes between the ones offered.
min	The earliest time.
max	The latest time.
clearable	Shows an x that empties it.
disabled	Greys it out.
invalid	Paints the border in the error color.
on_change	Receives event.value: a datetime.time or None.
on_open	The list opened.
on_close	The list closed.

ui.TimePicker(self.alarm, format="h:mm A", minute_step=15, on_change=lambda e: setattr(self, "alarm", e.value))

format_date

format_date(value, fmt='YYYY-MM-DD', *, language=None)

Writes a date with a pattern of tokens: YYYY 2026, YY 26, MMMM October, MMM Oct, MM 10, M 10, DD 05, D 5, dddd Monday, ddd Mon, HH/hh hours, mm minutes, ss seconds, A AM/PM and [text] kept as is. A pattern with % is a strftime one. Month and day names follow the language of pyzed.i18n.

Parameter	Description
value	A date, a datetime, ISO text or None (gives "").
fmt	The pattern.
language	A language for the names instead of the current one.

ui.format_date(day, "dddd, D MMMM YYYY")   # "Monday, 5 October 2026"

parse_date

parse_date(text, fmt='YYYY-MM-DD', *, language=None)

Reads a date written with a pattern of format_date (month names in the current language or English); ISO YYYY-MM-DD always works. Returns None when the text is not a date.

Parameter	Description
text	The text.
fmt	The pattern.
language	The language of the names.

format_time

format_time(value, fmt='HH:mm')

Writes a time (or "14:30") with a pattern such as "h:mm A".

Parameter	Description
value	A datetime.time or text.
fmt	The pattern.

parse_time

parse_time(text, fmt='HH:mm')

Reads a time: "14:30", "2:30 PM", "14:30:05", with fmt first. None when it is not one.

Parameter	Description
text	The text.
fmt	The pattern.

System

file_input

file_input(
    value,
    on_change=None,
    *,
    mode='open',
    filters=None,
    title=None,
    directory=None,
    file_name='',
    placeholder=None,
    button=None,
    editable=True,
    disabled=False,
    invalid=False,
    id=None,
    width='fill',
    theme=None,
)

A path field with a button that opens the system’s file dialog, so nobody types a path by hand. See the File picker page.

Parameter	Description
value	Current value.
on_change	Receives the path (a list with "open_many").
mode	"open" (a file), "open_many" (a list), "save" or "folder".
filters	Files shown: {"Images": "png jpg"} or "Images: png, jpg".
title	The dialog’s title.
directory	Where the dialog opens (default: the folder of the current path).
file_name	The name suggested when saving.
placeholder	Hint text shown when empty.
button	Text for the button instead of a folder icon.
editable	False keeps the path from being typed.
disabled	Disables it (ignores clicks).
invalid	Paints the border in the error color.
id	Stable identifier used to focus or scroll it with a Command.
width	Width: pixels, "fill", "shrink" or "fill:N" (proportion).
theme	Theme to use instead of the current one (pyzed.theme.current()).

ui.file_input(self.photo, self.set_photo, filters={"Images": "png jpg"})

pick

pick(then, *, mode='open', title=None, filters=None, directory=None, file_name='')

The system’s file dialog as a Command: return it from a callback and then receives what the user chose (a path, a list of paths with "open_many", or None when they cancel). ui.file_input uses it.

Parameter	Description
then	Called with the result.
mode	"open", "open_many", "save" or "folder".
title	The dialog’s title.
filters	Files shown: {"Images": "png jpg"} or "Images: png, jpg".
directory	Where the dialog opens.
file_name	The name suggested when saving.

ui.button("Open…", lambda: ui.system.pick(self.load, filters="Text: txt, md"))

DropZone

class DropZone

A component that takes files dragged from the system’s file manager and dropped on the window, and opens the file dialog on a click. It lights up while files are dragged over the window and keeps the dropped paths in files. The window’s on_file_drop hook hands each file to the zone under the pointer, else to one whose accept lists its type. See the Drop zone page.

Parameter	Description
text	The main text (default: Drop files here).
hint	The line under it.
icon_name	Its icon.
accept	Extensions (["png", "jpg"]), patterns ("*.tar.gz") or "folder"; empty takes everything.
multiple	False keeps only the last file.
browse	A click opens the file dialog.
show_files	Lists the files under the text (each with an x).
files	The dropped paths.
disabled	Takes nothing.
live	False draws it without taking files (the designer’s canvas).
on_drop	Receives event.value: one dropped path (once per file).
on_files	Receives event.value: the list of files.
on_reject	Receives a path it does not accept.
on_enter	Files are dragged over the window.
on_leave	The drag left without dropping.

ui.DropZone(accept=["png", "jpg"], on_drop=lambda e: self.photos.append(e.value))

Agent

ToolCall

class ToolCall

A component for one action of an AI agent, like the cards in Zed’s Agent panel: a header with the status, the title and what it works on, which unfolds to show the input and the output. While status is "waiting" it asks right on the card: Allow, Always allow or Deny. See AI agents.

Parameter	Description
title	What it does (“Edit file”).
detail	What it works on, in a monospace font.
kind	ACP’s kind: read, edit, delete, move, search, execute, think, fetch or other (its icon).
status	pending, running, waiting, done, failed or rejected.
input	The arguments (a dict or text).
output	The answer (text or a dict).
images	PNG bytes shown under the output.
diffs	The edits it made: {"path", "old", "new"} dicts, shown as colored diffs (see ui.diff_view).
progress	What it printed so far (a command’s output); its last lines show under the header while it runs.
allow_always	Shows Always allow.
theme	Theme.
on_allow	Allow was pressed.
on_allow_always	Always allow was pressed.
on_deny	Deny was pressed.

ui.ToolCall(title="Edit file", detail="ui/main.py", kind="edit", status=self.status,
            on_allow=lambda e: self.answer(True), on_deny=lambda e: self.answer(False))

Methods and properties

ToolCall.toggle

ToolCall.toggle()

Unfolds or folds the input and output.

Plan

class Plan

A component for an agent’s plan: a checklist with done/total in its header, which folds it.

Parameter	Description
steps	`{“step”: text, “status”: “pending”
running	Spins the step in progress.
theme	Theme.

ui.Plan(steps=[{"step": "Add the form", "status": "done"}, {"step": "Wire it", "status": "in_progress"}])

Methods and properties

Plan.toggle

Plan.toggle()

Folds or unfolds the steps.

EditsBar

class EditsBar

A component listing the files an agent changed, like Zed’s edits bar: 3 files changed with Reject all and Keep all, unfolding to one row per file with its diff stat, Reject and Keep.

Parameter	Description
files	Dicts or objects with path and optional added and removed line counts.
theme	Theme.
on_keep	Keep all.
on_reject	Reject all.
on_keep_file	Keep on a file (event.value is its path).
on_reject_file	Reject on a file.
on_open	A file was clicked.

ui.EditsBar(files=[{"path": "ui/main.py", "added": 12, "removed": 3}], on_keep=lambda e: self.keep())

Methods and properties

EditsBar.toggle

EditsBar.toggle()

Shows or hides the row of each file.

ThreadHistory

class ThreadHistory

A component for past conversations: a search box and the threads grouped by day (Today, Yesterday, This week, This month, Older), each with a delete button.

Parameter	Description
threads	Dicts or objects with id, title, updated (a timestamp) and an optional detail.
selected	The id of the open thread.
theme	Theme.
on_open	A thread was picked (event.value is its id).
on_delete	Delete was pressed on a thread.

ui.ThreadHistory(threads=self.threads, on_open=lambda e: self.open(e.value))

Methods and properties

ThreadHistory.set_query

ThreadHistory.set_query(text)

Filters the threads by text.

ThreadHistory.visible

ThreadHistory.visible()

The threads whose title or detail has every word of the search.

AuthPrompt

class AuthPrompt

A component that asks to sign in, like Zed when an agent needs it: one button per way to sign in, then, while one runs, what is happening (the browser or a terminal is open), a code to type when there is one, Open the page again and Cancel.

Parameter	Description
title	The heading.
detail	A line under it.
methods	Dicts with id, name, optional description and icon; the first is the main one.
waiting	The id of the method in progress ("" when none).
waiting_text	What to show while waiting.
code	A code to type (device sign-in).
url	The page that was opened.
error	An error to show.
icon_name	The icon.
theme	Theme.
on_pick	A method was picked (event.value is its id).
on_cancel	Cancel.
on_open_url	Open the page again.
on_copy	The code was copied.

ui.AuthPrompt(title="Sign in to Gemini", methods=[{"id": "google", "name": "Log in with Google"}], on_pick=self.sign_in)

ServiceRow

class ServiceRow

A component for one thing an agent uses (an MCP server, an external agent, a skill), like the rows of Zed’s agent settings: a status dot, the name and command, an on/off switch, a main button and a ⋯ menu.

Parameter	Description
name	Name.
detail	The command or URL, in a monospace font.
summary	A line about it.
icon_name	The icon.
status	running, starting, error, off, installed, missing or update (the dot’s color).
status_text	The dot’s tooltip; shown under the name for errors and updates.
version	A version or a source.
enabled	The switch (None hides it).
busy	Shows a spinner.
primary	Text of the main button (Update, Install…).
actions	ui.MenuItem entries of the ⋯ menu.
theme	Theme.
on_toggle	The switch was flipped.
on_primary	The main button was pressed.

ui.ServiceRow(name="github", detail="npx -y @modelcontextprotocol/server-github", status="running", enabled=True)

Methods and properties

ServiceRow.toggle_menu

ServiceRow.toggle_menu()

Opens or closes the ⋯ menu.

Catalog

class Catalog

A component for things to install with a search box (agents from a registry, servers, skills…): each row shows Install, Installed or Update to a newer version.

Parameter	Description
items	Dicts or objects with id, name and optional version, description, installed and update.
busy	The id being installed (a spinner).
height	Height of the list.
theme	Theme.
on_install	Install or Update was pressed (event.value is the id).

ui.Catalog(items=self.registry, busy=self.installing, on_install=lambda e: self.install(e.value))

Methods and properties

Catalog.set_query

Catalog.set_query(text)

Filters the items by text.

Catalog.visible

Catalog.visible()

The items whose id, name or description has every word of the search.

context_meter

context_meter(used, limit, *, theme=None)

How full a model’s context window is, like Zed’s token counter: a small ring and 48k / 200k, yellow past 80% and red past 95%.

Parameter	Description
used	Tokens in use.
limit	The model’s window.
theme	Theme.

format_tokens

format_tokens(count)

A short token count: 950, 4.5k, 48k, 1.25M.

Parameter	Description
count	Tokens.

diff_view

diff_view(diff, *, theme=None, max_lines=120)

An edit as Zed shows it in a thread: the file’s name, then the changed lines (green added, red removed) with a few lines around them.

Parameter	Description
diff	A dict with path, old and new (the texts before and after).
theme	Theme.
max_lines	Lines shown before … N more lines.

ui.diff_view({"path": "main.py", "old": "x = 1\n", "new": "x = 2\n"})

Icon picker

IconPicker

class IconPicker

A component that picks a Lucide icon: a search box (names and tags), a category drop-down and a grid that only builds the rows in view. Enter picks the first match. on_change gets the icon’s name ("" when cleared); pass it back as value. See the Icon picker page.

Parameter	Description
value	The picked icon’s name.
columns	Icons per row.
height	Height of the grid.
clearable	Shows a button that clears the icon.
autofocus	Focuses the search box when it appears.
on_change	Receives event.value.

ui.IconPicker(value=self.icon, on_change=lambda e: setattr(self, "icon", e.value))

Methods and properties

IconPicker.set_query

IconPicker.set_query(text)

Filters the grid by text (names and tags).

IconPicker.set_group

IconPicker.set_group(key)

Shows only the icons of category key ("" for every icon).

IconPicker.matches

IconPicker.matches()

The icons shown: those of the chosen category that match the search, best first.

IconPicker.pick

IconPicker.pick(name)

Selects name and emits change.

icon_picker_dialog

icon_picker_dialog(
    value,
    on_pick,
    *,
    on_close=None,
    title=None,
    columns=10,
    clearable=True,
    key='icon-picker',
    theme=None,
)

A dialog with an IconPicker that picks on a click; use it as the dialog of ui.dialog_layer. The search box gets the focus.

Parameter	Description
value	The current icon.
on_pick	Called with the clicked icon’s name ("" when cleared).
on_close	The close button.
title	Default: “Choose an icon”, translated.
columns	Icons per row.
clearable	Shows the “No icon” button.
key	Component key, for several pickers in one view.
theme	Theme.

ui.dialog_layer(page, ui.icon_picker_dialog(self.icon, self.pick, on_close=self.close) if self.picking else None,
                on_dismiss=self.close)

icon_grid

icon_grid(
    names,
    on_pick,
    *,
    selected=None,
    columns=8,
    cell=34,
    height=288,
    id=None,
    theme=None,
)

The bare grid of icons, virtualized: only the rows in view are built, so thousands of icons cost the same as a few.

Parameter	Description
names	Icon names, in order.
on_pick	Called with the clicked name.
selected	The highlighted name.
columns	Icons per row.
cell	Side of each cell in pixels.
height	Height of the grid.
id	Id of the scrollable, for Command.scroll_to.
theme	Theme.

Console and help

reference_browser

reference_browser(
    browser,
    *,
    on_open_url=None,
    sidebar_width=270,
    width='fill',
    height='fill',
    theme=None,
)

The built-in reference, like Godot’s: a searchable class list next to the page that is open.

browser is a pyzed.reference.Browser (keep it in your app’s state); clicking entries, links and the back/forward buttons changes it. on_open_url(url) gets the links that leave the reference (the website, GitHub…):

self.help = reference.Browser("pyzed.ui.button")
...
ui.reference_browser(self.help, on_open_url=open_in_browser)

Events:

• on_open_url(url): Called with the URL of a link that leaves the reference (open it in the browser).