Service row

ui.ServiceRow is a component for one thing an AI agent uses (an MCP server, an external agent, a skill) on a settings page: an icon, the name with its version and a status dot, the detail (its command or URL, in a monospace font) and a summary; then a spinner while busy, a main button (primary, such as Update or Install), an on/off switch (enabled; None hides it) and a ⋯ menu with the actions (ui.MenuItem). status colors the dot: running and installed green, starting yellow, update in the accent color, error red, off and missing gray. status_text is the dot’s tooltip, and it shows under the name for error, missing and update.

ui.ServiceRow · Category: AI agents · Full reference →

Preview
Code

pz.column([
    ui.ServiceRow(name="github", detail="npx -y @modelcontextprotocol/server-github", icon_name="github",
                  status="running", enabled=True, on_toggle=on_toggle,
                  actions=[ui.MenuItem("Edit", on_edit, icon="pencil")]),
    ui.ServiceRow(name="filesystem", detail="uvx mcp-server-filesystem ~/notes", status="error",
                  status_text="Exited with code 1", enabled=True, on_toggle=on_toggle),
    ui.ServiceRow(name="Gemini CLI", version="0.64.0", icon_name="bot", status="update",
                  status_text="0.65.0 is available", primary="Update", on_primary=on_update),
], spacing=4, width=560)

When to use

In the settings of an app with AI agents: one row per MCP server, agent or skill.
For any list of services that can be turned on and off, updated or removed.

Usage

import pyzed as pz
from pyzed import ui

class Settings(pz.App):
    def __init__(self):
        self.on = True

    def view(self):
        return ui.ServiceRow(name="github", detail="npx -y @modelcontextprotocol/server-github",
                             status="running" if self.on else "off", enabled=self.on,
                             on_toggle=lambda e: setattr(self, "on", e.value),
                             actions=[ui.MenuItem("Remove", self.remove, icon="trash-2", danger=True)])

Variants

State

enabled=False also dims the name and the icon.

Service row: status="running" — `status="running"`

Service row: status="starting" — `status="starting"`

Service row: status="error" — `status="error"`

Service row: status="off" — `status="off"`

Service row: status="installed" — `status="installed"`

Service row: status="missing" — `status="missing"`

Service row: status="update" — `status="update"`

Options

The ⋯ menu is drawn open, as after a click on it.

Service row: actions=[...] — `actions=[...]`

Events

Service row has 2 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.

It is a pz.Component, so it also raises on_mount and on_unmount, and its handlers get a pz.Event whose value holds the data.

Event	Handler gets	When
`on_toggle`	`(event)`	The switch was flipped.
`on_primary`	`(event)`	The main button was pressed.

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 Settings(pz.App):
    def __init__(self):
        self.on = True
        self.updates = 0

    def view(self):
        return ui.ServiceRow(name="github", status="running" if self.on else "off", enabled=self.on,
                             primary="Update",
                             on_toggle=lambda e: setattr(self, "on", e.value),     # the switch
                             on_primary=lambda e: setattr(self, "updates", self.updates + 1))

from dataclasses import dataclass


@dataclass
class Enable:
    on: bool


class Settings(pz.App):
    on = True

    def update(self, message):
        match message:
            case Enable(on):
                self.on = on

    def view(self):
        return ui.ServiceRow(name="github", enabled=self.on, status="running" if self.on else "off",
                             on_toggle=lambda e: Enable(e.value))

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    on: bool = True


def view(state, set_state):
    return ui.ServiceRow(name="github", enabled=state.on, status="running" if state.on else "off",
                         on_toggle=lambda e: set_state(on=e.value))

Properties and API

`ui.ServiceRow`

class ServiceRow

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

Property	Default	Description
`name`	`""`	Name.
`detail`	`""`	The command or URL, in a monospace font.
`summary`	`""`	A line about it.
`icon_name`	`"plug"`	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`	`None`	The switch (`None` hides it).
`busy`	`False`	Shows a spinner.
`primary`	`""`	Text of the main button (Update, Install…).
`actions`	`None`	`ui.MenuItem` entries of the `⋯` menu.
`theme`	`None`	Theme.

Events: on_toggle, on_primary (events).

Full reference →

CatalogThings to install, with a search box and Install or Update.

SwitchAn on/off switch for settings that apply at once.

MenuA context menu with icons, shortcuts and checks.

Settings groupA titled block of field rows, for settings screens.