List item

A list row: an icon, the text and start/end slots for any widget. It supports selected, focused (focus border), disabled, nesting with indent, and on_right_press for a context menu.

ui.list_item · Category: Lists and menus · Full reference →

Preview
Code

pz.column([
    ui.list_item("main.py", on_open, icon="file-code", icon_color="#3572a5", selected=True, inset=True),
    ui.list_item("README.md", on_open, icon="file-text", inset=True, end=ui.badge("M", tint="warning")),
    ui.list_item("Cargo.toml", on_open, icon="file-cog", inset=True, end=ui.kbd("ctrl-1", size="xs")),
    ui.list_item("old.txt", on_open, icon="file", inset=True, disabled=True),
], width=320)

When to use

For any vertical list: recent files, search results, settings categories, people.
Use inset=True inside panels so the highlight has a margin.

Usage

import pyzed as pz
from pyzed import ui

class Recent(pz.App):
    def __init__(self):
        self.files = ["main.py", "app.py", "README.md"]
        self.current = "main.py"

    def view(self):
        return pz.column([
            ui.list_item(f, lambda f=f: setattr(self, "current", f), icon="file",
                         selected=f == self.current, inset=True)
            for f in self.files
        ])

Variants

Content

List item: color="error" — `color="error"`

State

List item: selected=True — `selected=True`

List item: focused=True — `focused=True`

List item: disabled=True — `disabled=True`

States and events

on_right_press opens a context menu and tooltip= shows on hover.

List item: description= — `description=`

List item: on_double_press= — `on_double_press=`

Events

List item has 3 events of its own, listed below. Like every widget it also has the 18 common events (click, double_click, right_click, mouse_enter, drag, key_down, resize…), attached with .on(...): see Events and Events of every component.

Event	Handler gets	When
`on_press`	`()`	Message or callable sent on press. `None` disables the control.
`on_right_press`	`()`	Right click.
`on_double_press`	`()`	Sent on a double click (open, rename…).

Handler gets is what Pyzed passes to your callable: () means nothing. Any handler can also be a message (a value that is not callable), which goes to update().

Handling the events

The same events written three ways. Imperative: methods of the app change self. Declarative: the handlers produce messages and one update() decides. Functional: a pure function draws an immutable state and asks for changes with set_state(...). See Imperative, declarative and functional.

class Recent(pz.App):
    def __init__(self):
        self.files = ["main.py", "app.py", "README.md"]
        self.current = "main.py"
        self.opened = None

    def view(self):
        return pz.column([
            ui.list_item(f, lambda f=f: setattr(self, "current", f), icon="file",   # on_press
                         selected=f == self.current, inset=True,
                         on_double_press=lambda f=f: setattr(self, "opened", f),
                         on_right_press=lambda f=f: print("menu for", f))
            for f in self.files
        ], width=280)

from dataclasses import dataclass


@dataclass
class Select:
    path: str


@dataclass
class Open:
    path: str


class Recent(pz.App):
    files = ["main.py", "app.py", "README.md"]
    current, opened = "main.py", None

    def update(self, message):
        match message:
            case Select(path):
                self.current = path
            case Open(path):
                self.opened = path

    def view(self):
        return pz.column([ui.list_item(f, Select(f), icon="file", selected=f == self.current,
                                       on_double_press=Open(f)) for f in self.files], width=280)

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    files: tuple = ("main.py", "app.py", "README.md")
    current: str = "main.py"


def file_row(name, selected, select):
    return ui.list_item(name, select, icon="file", selected=selected, inset=True)


def view(state, set_state):
    return pz.column([file_row(f, f == state.current, lambda f=f: set_state(current=f))
                      for f in state.files], width=280)

Properties and API

`ui.list_item`

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

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

Property	Default	Description
`content`	required	Text or widget.
`icon`	`None`	Name of a Lucide icon (`pyzed icons` lists them).
`icon_color`	`None`	Icon color: a theme token or a hex color.
`start`	`None`	Widgets at the start (left).
`end`	`None`	Widgets at the end (right).
`selected`	`False`	Marks it as selected.
`focused`	`False`	Draws a focus border.
`indent`	`0`	Left indentation, in pixels.
`height`	`26`	Row height.
`color`	`None`	Text color.
`inset`	`False`	With margin and rounded corners (menus, palettes).
`disabled`	`False`	Disables it (ignores clicks).
`description`	`None`	A muted second line (the row grows to 40 px unless `height` is set).
`tooltip`	`None`	Text shown on hover.
`theme`	`None`	Theme to use instead of the current one (`pyzed.theme.current()`).

Events: on_press, on_right_press, on_double_press (events).

Full reference →

List headerA small section title for lists, with an end slot.

TreeA collapsible file tree with icons and git colors.

MenuA context menu with icons, shortcuts and checks.