Calendar

ui.Calendar shows one or more months. mode picks a single day ("single"), a range ("range", two clicks) or any number of days ("multiple", each click toggles one). The header switches to a grid of months and then of years to jump far, and the arrows of the keyboard move the focused day (Page Up/Page Down by month, Enter picks). The pickers on this page open one of these in a popup.

ui.Calendar · Category: Dates and times · Full reference →

Preview
Code

pz.row([
    ui.Calendar(value="2026-10-22", today_button=True, on_change=on_change),
    ui.Calendar(value=("2026-10-05", "2026-10-14"), mode="range", disabled=["weekend"], on_change=on_change),
], spacing=24)

When to use

In a side panel or a dashboard, where the calendar stays visible.
first_weekday ("monday", "sunday"…) and week_numbers=True follow local customs.
Inside a form field, use Date picker instead.

Usage

import pyzed as pz
from pyzed import ui

class Planner(pz.App):
    def __init__(self):
        self.days = []

    def view(self):
        return pz.row([
            ui.Calendar(value=self.days, mode="multiple", week_numbers=True,
                        on_change=lambda e: setattr(self, "days", e.value)),
            pz.column([ui.label(ui.format_date(d, "ddd D MMM")) for d in self.days], spacing=4),
        ], spacing=16)

Variants

Mode

Calendar: mode="multiple" — `mode="multiple"`

Options

Calendar: week_numbers=True — `week_numbers=True`

Calendar: first_weekday="sunday" — `first_weekday="sunday"`

Calendar: min, max, disabled — `min, max, disabled`

Calendar: show_outside=False — `show_outside=False`

Views

A click on the title goes to the months, and another one to the years.

Calendar: set_view("months") — `set_view("months")`

Calendar: set_view("years") — `set_view("years")`

Events

Calendar 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_change`	`(event)`	Receives `event.value` (a date, a tuple or a list).
`on_month`	`(event)`	Receives `event.value`, the `(year, month)` shown.

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 Planner(pz.App):
    def __init__(self):
        self.days = []

    def changed(self, event):            # on_change: the list of days ("multiple" mode)
        self.days = event.value

    def view(self):
        return pz.row([
            ui.Calendar(value=self.days, mode="multiple", on_change=self.changed),
            ui.label(f"{len(self.days)} days"),
        ], spacing=16)

from dataclasses import dataclass


@dataclass
class Day:
    value: object


class Planner(pz.App):
    day = None

    def update(self, message):
        match message:
            case Day(value):
                self.day = value

    def view(self):
        return ui.Calendar(value=self.day, today_button=True, on_change=lambda e: Day(e.value))

from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    stay: tuple = ("2026-10-05", "2026-10-09")


def view(state, set_state):
    return ui.Calendar(value=state.stay, mode="range", months=2, on_change=lambda e: set_state(stay=e.value))

Properties and API

`ui.Calendar`

class Calendar

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

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

Events: on_change, on_month (events).

Full reference →

Date pickerA date field with a calendar that drops down, in the format you choose.

Date range pickerTwo dates in one field, with two months side by side and quick ranges.