Segmented

In plain words

A row of joined buttons where exactly one is chosen, like Day / Week / Month in a calendar.

A row of joined buttons where one is selected. on_select receives the chosen option.

ui.segmented · Category: Forms · Full reference →

Preview

Code

pz.column([
    ui.segmented(["Editor", "Terminal", "Both"], "Editor", on_select),
    ui.segmented(["Day", "Week", "Month"], "Week", on_select),
], spacing=14, align="center")

When to use

• To switch between two to five views or modes (Day / Week / Month).
• For icons only, use a Toggle group.

Usage

import pyzed as pz
from pyzed import ui

class Calendar(pz.App):
    def __init__(self):
        self.mode = "Week"

    def view(self):
        return ui.segmented(["Day", "Week", "Month"], self.mode, lambda m: setattr(self, "mode", m))

Variants

About these captures

Each capture is recorded by pyzed itself, off-screen at 2x, in One Dark or One Light to match this site’s theme, and cropped to the component so it shows at its real size. The pointer hovers, presses or types into it; a component that does not react to the pointer cycles through a few themes. With reduced motion you see the first frame. Open Code under a capture to see the snippet that draws it; free names such as on_save stand for your own callbacks.

Options

Two options

Code

ui.segmented(["Code", "Preview"], "Code", on_select)

Three options

Code

ui.segmented(["Day", "Week", "Month"], "Week", on_select)

Five options

Code

ui.segmented(["XS", "S", "M", "L", "XL"], "M", on_select)

Selection

First

Code

ui.segmented(["Editor", "Terminal", "Both"], "Editor", on_select)

Last

Code

ui.segmented(["Editor", "Terminal", "Both"], "Both", on_select)

States and events

With icons

Code

ui.segmented([("list", "List", "list"), ("grid", "Grid", "layout-grid")], "grid", on_select)

width="fill"

Code

ui.segmented(["Day", "Week", "Month"], "Week", on_select, width=320)

disabled={"Month"}

Code

ui.segmented(["Day", "Week", "Month"], "Day", on_select, disabled={"Month"})

size="sm"

Code

ui.segmented(["Code", "Preview"], "Code", on_select, size="sm")

Events

Segmented has 1 event 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_select	(item)	Callable that receives the chosen item.

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.

Imperative

class Calendar(pz.App):
    def __init__(self):
        self.mode = "Week"

    def view(self):
        return pz.column([
            ui.segmented(["Day", "Week", "Month"], self.mode, lambda m: setattr(self, "mode", m)),
            ui.label(f"Showing a {self.mode.lower()}"),
        ], spacing=8, align="center")

Declarative

from dataclasses import dataclass


@dataclass
class Mode:
    name: str


class Calendar(pz.App):
    mode = "Week"

    def update(self, message):
        match message:
            case Mode(name):
                self.mode = name

    def view(self):
        return ui.segmented(["Day", "Week", "Month"], self.mode, Mode)

Functional

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    mode: str = "Week"


def view(state, set_state):
    return ui.segmented(["Day", "Week", "Month"], state.mode, lambda m: set_state(mode=m))

Tips

Tip

Once clicked or reached with Tab it has the keyboard focus: ←/→ pick the previous or next option (skipping disabled ones) and Home/End the first and last.

Properties and API

ui.segmented

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

A group of mutually exclusive buttons.

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

Events: on_select (events).

Full reference →

Related

Toggle groupAn icon-only segmented control.

Radio groupMutually exclusive options as radio buttons.

Tab barEditor tabs with icons, dirty dots and close buttons.