# Components (pyzed.ui)

> API reference for pyzed.ui: every ready-made component, its parameters, defaults and events, for building native Python desktop apps.

Source: https://albakore.github.io/pyzed/reference/ui/

<!-- Generated by docs/scripts/gen_api.py. Edit docs/scripts/api_docs_en.py. -->

Signatures and parameters of every component. To see them with images and examples,
go to the [Components](https://albakore.github.io/pyzed/components/overview/) 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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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()`). |

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

### `switch`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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](https://albakore.github.io/pyzed/guides/i18n/#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()`). |

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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()`). |

```python
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`

```python
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). |

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

**Methods and properties**

#### `Log.write`

```python
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`

```python
Log.find(entry_id)
```

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

#### `Log.clear`

```python
Log.clear()
```

Removes every entry.

#### `Log.counts`

```python
Log.counts()
```

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

#### `Log.text`

```python
Log.text(ids=None)
```

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

#### `Log.capturing`

```python
Log.capturing  # property
```

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

#### `Log.capture`

```python
Log.capture()
```

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

#### `Log.release`

```python
Log.release()
```

Stops capturing and puts the original streams back.

#### `Log.pipe`

```python
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`

```python
@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`

```python
LogEntry.clock  # property
```

The entry's local time as `HH:MM:SS`.

#### `LogEntry.line`

```python
LogEntry.line(*, details=True)
```

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

### `LogSelection`

```python
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' `id`s for `log.text(ids)`.

```python
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`

```python
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`

```python
LogSelection.select(ids)
```

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

#### `LogSelection.clear`

```python
LogSelection.clear()
```

Selects nothing.

#### `LogSelection.keep`

```python
LogSelection.keep(entries)
```

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

### `LOG_LEVELS`

```python
LOG_LEVELS(...)
```

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

### `console`

```python
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`

```python
@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()`). |

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

**Methods and properties**

#### `ErrorInfo.from_exception`

```python
@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`

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

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

#### `ErrorInfo.summary`

```python
ErrorInfo.summary  # property
```

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

#### `ErrorInfo.location`

```python
ErrorInfo.location  # property
```

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

#### `ErrorInfo.report`

```python
ErrorInfo.report()
```

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

### `error_boundary`

```python
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. |

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

### `error_card`

```python
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`

```python
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. |

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
@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`

```python
Column.value(row)
```

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

### `table`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
@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`

```python
TreeNode.is_folder  # property
```

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

#### `TreeNode.from_paths`

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

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

#### `TreeNode.sort`

```python
TreeNode.sort()
```

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

### `tree`

```python
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`

```python
@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`

```python
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`

```python
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`

```python
@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`

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

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

### `tab`

```python
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`

```python
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](https://albakore.github.io/pyzed/guides/windows/#draggable-tabs-and-detachable-windows).

| 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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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()`). |

```python
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`

```python
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`

```python
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`

```python
@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. |

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

### `system_platform`

```python
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`

```python
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`

```python
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`

```python
@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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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`

```python
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" | "modified" | "deleted"}`. |
| `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`

```python
language_token(path)
```

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

| Parameter | Description |
| --- | --- |
| `path` | File path. |

### `terminal`

```python
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`

```python
ansi(text)
```

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

| Parameter | Description |
| --- | --- |
| `text` | Text with ANSI escapes. |

## Color picker

### `ColorPicker`

```python
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](https://albakore.github.io/pyzed/theming/styles/#color-picker).

| 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`. |

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

**Methods and properties**

#### `ColorPicker.parts`

```python
ColorPicker.parts()
```

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

#### `ColorPicker.build`

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

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

#### `ColorPicker.publish`

```python
ColorPicker.publish(*parts)
```

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

#### `ColorPicker.current`

```python
ColorPicker.current()
```

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

#### `ColorPicker.set_color`

```python
ColorPicker.set_color(color)
```

Replaces the selected stop's color with `color` and publishes the result.

#### `ColorPicker.hsva`

```python
ColorPicker.hsva()
```

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

#### `ColorPicker.pick_sv`

```python
ColorPicker.pick_sv(event)
```

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

#### `ColorPicker.pick_hue`

```python
ColorPicker.pick_hue(event)
```

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

#### `ColorPicker.pick_alpha`

```python
ColorPicker.pick_alpha(event)
```

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

#### `ColorPicker.type_hex`

```python
ColorPicker.type_hex(text)
```

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

#### `ColorPicker.set_alpha_percent`

```python
ColorPicker.set_alpha_percent(value)
```

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

#### `ColorPicker.set_mode`

```python
ColorPicker.set_mode(mode)
```

Switches between `"Solid"` and `"Gradient"`.

#### `ColorPicker.set_angle`

```python
ColorPicker.set_angle(value)
```

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

#### `ColorPicker.select_stop`

```python
ColorPicker.select_stop(index)
```

Selects the gradient stop at `index` for editing.

#### `ColorPicker.move_stop`

```python
ColorPicker.move_stop(index, event)
```

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

#### `ColorPicker.add_stop`

```python
ColorPicker.add_stop(event)
```

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

#### `ColorPicker.remove_stop`

```python
ColorPicker.remove_stop()
```

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

#### `ColorPicker.toggle_mask`

```python
ColorPicker.toggle_mask(on)
```

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

#### `ColorPicker.select_mask_stop`

```python
ColorPicker.select_mask_stop(index)
```

Selects the mask stop at `index` for editing.

#### `ColorPicker.move_mask_stop`

```python
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`

```python
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`

```python
ColorPicker.set_mask_opacity(value)
```

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

#### `ColorPicker.remove_mask_stop`

```python
ColorPicker.remove_mask_stop()
```

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

#### `ColorPicker.marker`

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

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

#### `ColorPicker.area`

```python
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`

```python
ColorPicker.sv_area()
```

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

#### `ColorPicker.hue_bar`

```python
ColorPicker.hue_bar()
```

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

#### `ColorPicker.alpha_bar`

```python
ColorPicker.alpha_bar()
```

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

#### `ColorPicker.stops_bar`

```python
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`

```python
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`

```python
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`

```python
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](https://albakore.github.io/pyzed/library/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. |

```python
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`

```python
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](https://albakore.github.io/pyzed/library/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. |

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

### `DateRangePicker`

```python
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](https://albakore.github.io/pyzed/library/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. |

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

### `TimePicker`

```python
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](https://albakore.github.io/pyzed/library/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. |

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

### `format_date`

```python
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. |

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

### `parse_date`

```python
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`

```python
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`

```python
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`

```python
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](https://albakore.github.io/pyzed/library/file-input/) 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()`). |

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

### `pick`

```python
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. |

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

### `DropZone`

```python
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](https://albakore.github.io/pyzed/library/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. |

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

## Agent

### `ToolCall`

```python
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](https://albakore.github.io/pyzed/editor/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. |

```python
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`

```python
ToolCall.toggle()
```

Unfolds or folds the input and output.

### `Plan`

```python
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" | "in_progress" | "done"}` dicts. |
| `running` | Spins the step in progress. |
| `theme` | Theme. |

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

**Methods and properties**

#### `Plan.toggle`

```python
Plan.toggle()
```

Folds or unfolds the steps.

### `EditsBar`

```python
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. |

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

**Methods and properties**

#### `EditsBar.toggle`

```python
EditsBar.toggle()
```

Shows or hides the row of each file.

### `ThreadHistory`

```python
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. |

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

**Methods and properties**

#### `ThreadHistory.set_query`

```python
ThreadHistory.set_query(text)
```

Filters the threads by `text`.

#### `ThreadHistory.visible`

```python
ThreadHistory.visible()
```

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

### `AuthPrompt`

```python
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. |

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

### `ServiceRow`

```python
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. |

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

**Methods and properties**

#### `ServiceRow.toggle_menu`

```python
ServiceRow.toggle_menu()
```

Opens or closes the `⋯` menu.

### `Catalog`

```python
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). |

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

**Methods and properties**

#### `Catalog.set_query`

```python
Catalog.set_query(text)
```

Filters the items by `text`.

#### `Catalog.visible`

```python
Catalog.visible()
```

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

### `context_meter`

```python
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`

```python
format_tokens(count)
```

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

| Parameter | Description |
| --- | --- |
| `count` | Tokens. |

### `diff_view`

```python
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`. |

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

## Icon picker

### `IconPicker`

```python
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](https://albakore.github.io/pyzed/library/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`. |

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

**Methods and properties**

#### `IconPicker.set_query`

```python
IconPicker.set_query(text)
```

Filters the grid by `text` (names and tags).

#### `IconPicker.set_group`

```python
IconPicker.set_group(key)
```

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

#### `IconPicker.matches`

```python
IconPicker.matches()
```

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

#### `IconPicker.pick`

```python
IconPicker.pick(name)
```

Selects `name` and emits `change`.

### `icon_picker_dialog`

```python
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. |

```python
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`

```python
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`

```python
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...):

```python
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).