Date picker

In plain words

A box for a date. Type it, or press the little calendar and click a day.

ui.DatePicker is a text field for one date. The calendar button (or Alt+↓) opens a Calendar under it, and the user can also type the date: it is read with format when they press Enter or leave the field. With the focus in the field, ↑ and ↓ move one day and Page Up/Page Down one month, without opening anything. on_change receives a datetime.date (or None when the field is cleared) in event.value.

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

Preview

Code

pz.container(
    ui.DatePicker(value="2026-10-22", format="DD/MM/YYYY", on_change=on_change),
    width=220, height=330, align_y="start")

New

This component was added recently. Tell us how it works for you in the issue tracker.

When to use

• For birthdays, due dates, bookings and any form field that holds a date.
• format takes tokens (DD/MM/YYYY, MMM D, YYYY, dddd D MMMM) or a strftime pattern (%d.%m.%Y). Month and day names follow the app’s language.
• min, max and disabled_dates (dates, "weekend" or day names) turn days off.
• For two dates (from–to), use Date range picker.

Usage

import pyzed as pz
from pyzed import ui

import datetime


class Booking(pz.App):
    def __init__(self):
        self.day = datetime.date.today()

    def view(self):
        return pz.column([
            ui.field("Check-in", ui.DatePicker(value=self.day, format="ddd D MMM YYYY",
                                               min=datetime.date.today(), disabled_dates=["sunday"],
                                               on_change=lambda e: setattr(self, "day", e.value))),
            ui.label(f"Booked for {ui.format_date(self.day, 'dddd D MMMM')}"),
        ], spacing=12, width=320)

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.

Format

Tokens: YYYY YY, MMMM MMM MM M, DD D, dddd ddd; [text] is copied as is.

"YYYY-MM-DD"

Code

ui.DatePicker(value="2026-10-22", on_change=on_change)

"DD/MM/YYYY"

Code

ui.DatePicker(value="2026-10-22", format="DD/MM/YYYY", on_change=on_change)

"MMM D, YYYY"

Code

ui.DatePicker(value="2026-10-22", format="MMM D, YYYY", on_change=on_change)

"ddd D MMM"

Code

ui.DatePicker(value="2026-10-22", format="ddd D MMM", on_change=on_change)

States

placeholder

Code

ui.DatePicker(placeholder="Pick a date", on_change=on_change)

invalid=True

Code

ui.DatePicker(value="2026-10-22", invalid=True, on_change=on_change)

disabled=True

Code

ui.DatePicker(value="2026-10-22", disabled=True, on_change=on_change)

Open

Code

ui.DatePicker(value="2026-10-22", on_change=on_change)

Examples

Formats

ui.format_date and ui.parse_date use the same tokens as the field, for your own labels.

Preview

Code

pz.column([
    ui.label(ui.format_date("2026-10-22", "DD/MM/YYYY"), mono=True),
    ui.label(ui.format_date("2026-10-22", "MMM D, YYYY"), mono=True),
    ui.label(ui.format_date("2026-10-22", "dddd, D MMMM YYYY"), mono=True),
    ui.label(ui.format_date("2026-10-22", "[week of] D/M/YY"), mono=True),
], spacing=6)

Events

Date picker has 4 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	Of	Handler gets	When
on_change	ui.DatePicker	(event)	Receives event.value: a datetime.date or None.
on_open	ui.DatePicker	(event)	The calendar opened.
on_close	ui.DatePicker	(event)	The calendar closed.
on_dismiss	pz.popup	()	Message or callable sent on a press outside or Escape.

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

import datetime


class Booking(pz.App):
    def __init__(self):
        self.day = datetime.date(2026, 10, 22)

    def changed(self, event):            # on_change: event.value is a datetime.date (or None)
        self.day = event.value

    def view(self):
        return pz.column([
            ui.DatePicker(value=self.day, format="DD/MM/YYYY", on_change=self.changed),
            ui.label(ui.format_date(self.day, "dddd D MMMM") or "No date"),
        ], spacing=8, width=240)

Declarative

import datetime
from dataclasses import dataclass


@dataclass
class Picked:
    day: datetime.date


class Booking(pz.App):
    day = datetime.date(2026, 10, 22)

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

    def view(self):
        # DatePicker is a pz.Component: its handler gets a pz.Event
        return ui.DatePicker(value=self.day, on_change=lambda e: Picked(e.value))

Functional

import datetime
from dataclasses import dataclass


@dataclass(frozen=True)
class State:
    day: datetime.date = datetime.date(2026, 10, 22)


def view(state, set_state):
    return pz.column([
        ui.DatePicker(value=state.day, format="MMM D, YYYY", on_change=lambda e: set_state(day=e.value)),
        ui.label(f"Week {state.day.isocalendar().week}" if state.day else "No date"),
    ], spacing=8, width=240)

Tips

Tip

The calendar opens in a pz.popup, a layer drawn over the window: it is never clipped by a scrollable or a small container, flips above the field when there is no room below and closes with Escape or a click outside.

Properties and API

ui.DatePicker

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

Property	Default	Description
value	None	The date (datetime.date, ISO text or None).
format	"YYYY-MM-DD"	How it is written: "DD/MM/YYYY", "MMM D, YYYY"… (see format_date).
placeholder	""	Hint while empty (default: the format).
min	None	The earliest date.
max	None	The latest date.
disabled_dates	()	Days that cannot be picked (as in Calendar).
first_weekday	"monday"	"monday", "sunday" or "saturday".
week_numbers	False	Shows week numbers in the calendar.
clearable	True	Shows an x that empties it.
today_button	True	Adds a Today link to the calendar.
disabled	False	Greys it out.
invalid	False	Paints the border in the error color.

Events: on_change, on_open, on_close (events).

Full reference →

ui.format_date

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.

Property	Default	Description
value	required	A date, a datetime, ISO text or None (gives "").
fmt	"YYYY-MM-DD"	The pattern.
language	None	A language for the names instead of the current one.

Full reference →

ui.parse_date

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.

Property	Default	Description
text	required	The text.
fmt	"YYYY-MM-DD"	The pattern.
language	None	The language of the names.

Full reference →

pz.popup

popup(base, content=None, *, on_dismiss=None, side='bottom', align='start', gap=4.0)

Shows content over everything else next to base, like the menu of a drop-down: it is not cut off by the panels base sits in, flips to the other side when it does not fit and stays inside the window. A press outside it (and outside base) or Escape calls on_dismiss. With content=None only base is shown. The date pickers open their calendars with it.

Property	Default	Description
base	required	The widget it belongs to (a field, a button).
content	None	What opens (a panel, a menu), or None while closed.
side	"bottom"	"bottom", "top", "right" or "left" of base.
align	"start"	"start", "center" or "end": how it lines up with base.
gap	4.0	Space between base and the content.

Events: on_dismiss (events).

Full reference →

Related

CalendarA month grid to pick a day, a range or several days, always on screen.

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

Time pickerA time field with columns of hours and minutes, in 24 or 12 hours.

InputA controlled text field with icon, placeholder and password mode.