DateField

A date input field with locale-aware display formatting and an optional calendar picker button. Supports single-date and date-range selection modes.

Usage

Basic usage

bs.DateField(label="Select a date")

Display formats

The value_format= parameter controls how dates are displayed in the field. Any ICU date format pattern or named preset is accepted.

bs.DateField(value=today, value_format="longDate")     # January 15, 2025
bs.DateField(value=today, value_format="shortDate")    # 1/15/25
bs.DateField(value=today, value_format="monthAndYear") # January 2025
bs.DateField(value=today, value_format="yyyy-MM-dd")   # 2025-01-15

Range mode

Set selection_mode='range' to let the user pick a start and end date. The entry becomes read-only in this mode — dates must be chosen via the picker. value returns a (start, end) tuple of date objects.

df = bs.DateField(
    selection_mode="range",
    range_start=date(2025, 1, 1),
    range_end=date(2025, 1, 31),
    label="Date range",
)
start, end = df.value  # tuple[date, date]

Date constraints

Use min_date=, max_date=, or disabled_dates= to restrict which dates the picker shows as selectable.

from datetime import date, timedelta

today = date.today()
bs.DateField(
    label="Booking date",
    min_date=today,
    max_date=today + timedelta(days=30),
    disabled_dates=[today + timedelta(days=7)],
)

min_date, max_date, and disabled_dates are also live properties — assign to them to update the constraints (the change takes effect the next time the picker opens):

df.min_date = date.today()          # no past dates
df.disabled_dates = booked_dates

Reactive binding

Pass a Signal[str] via textsignal= to keep the field text in sync with application state.

date_sig = bs.Signal("")
bs.DateField(label="Pick a date", textsignal=date_sig)
bs.Label(textsignal=date_sig, accent="secondary")

Handling changes

on_change() fires whenever the selected date changes — whether by keyboard input, picker selection, or value= assignment.

df = bs.DateField(label="Appointment")
df.on_change(lambda e: print("Selected:", df.value))

States

bs.DateField(value=today, label="Normal")
bs.DateField(value=today, label="Read only", read_only=True)
bs.DateField(value=today, label="Disabled",  disabled=True)

Widget sizing

All widgets accept self-placement kwargs via **kwargs. The parent container determines which options apply — stack-based parents use stack kwargs, grid-based parents use grid kwargs. Unrecognised keys are silently ignored.

Stack

Used inside VStack, HStack, App, and other stack containers.

fill	Fill direction: 'x', 'y', 'both', or 'none'.
expand	Grow to consume extra space in the parent. True or False.
anchor	Alignment when the widget does not fill the available slot: 'n', 's', 'e', 'w', 'center', 'nw', etc.
margin	External spacing in pixels. Accepts an integer (equal on all sides), a 2-tuple (horizontal, vertical), or a 4-tuple (left, top, right, bottom).
margin_x	Horizontal external spacing (left and right). Accepts an integer or a 2-tuple (left, right) for asymmetric spacing. Overrides the horizontal component of margin=.
margin_y	Vertical external spacing (top and bottom). Accepts an integer or a 2-tuple (top, bottom) for asymmetric spacing. Overrides the vertical component of margin=.

Grid

Used inside a Grid container.

row / column	Zero-based row and column indices.
rowspan / columnspan	Number of rows or columns to span.
sticky	Alignment and fill within the grid cell. Any combination of 'n', 's', 'e', 'w' — e.g. 'ew' stretches horizontally, 'nsew' fills the entire cell.
margin	External spacing in pixels. Accepts an integer, a 2-tuple (horizontal, vertical), or a 4-tuple (left, top, right, bottom).
margin_x	Horizontal external spacing. Accepts an integer or (left, right).
margin_y	Vertical external spacing. Accepts an integer or (top, bottom).

See also

• TimeField — time input with clock picker

• TextField — plain single-line text input

API

The complete reference for DateField lives on the Widgets API page. At a glance:

DateField

A date input field with an optional calendar picker button.

Full Example

with bs.App(title="DateField Demo", padding=20, gap=16) as app:

    # Basic usage
    bs.Label("Basic", font="heading-sm")
    bs.DateField(label="Select a date")

    # Date format presets
    bs.Label("Display Formats", font="heading-sm")
    today = date.today()
    bs.DateField(value=today, label="Long date (default)",   value_format="longDate")
    bs.DateField(value=today, label="Short date",            value_format="shortDate")
    bs.DateField(value=today, label="Month and year",        value_format="monthAndYear")

    # Range mode
    bs.Label("Range Mode", font="heading-sm")
    bs.DateField(
        selection_mode="range",
        range_start=date(today.year, today.month, 1),
        range_end=today,
        label="Date range",
        message="Select a start and end date.",
    )

    # Min / max date constraints
    bs.Label("Constrained Dates", font="heading-sm")
    from datetime import timedelta
    bs.DateField(
        label="Booking date",
        message="Must be within the next 30 days.",
        min_date=today,
        max_date=today + timedelta(days=30),
    )

    # Reactive binding
    bs.Label("Reactive Binding", font="heading-sm")
    date_sig = bs.Signal("")
    df = bs.DateField(label="Pick a date", textsignal=date_sig)
    bs.Label(textsignal=date_sig, accent="secondary")

    # States
    bs.Label("States", font="heading-sm")
    bs.DateField(value=today, label="Normal")
    bs.DateField(value=today, label="Read only", read_only=True)
    bs.DateField(value=today, label="Disabled",  disabled=True)

    # Handling changes
    bs.Label("Handling Changes", font="heading-sm")
    last = bs.Signal("(none)")
    picker = bs.DateField(label="Choose a date")
    picker.on_change(lambda e: last.set(str(picker.value)))
    bs.Label(textsignal=last, accent="secondary")

    # Validation
    bs.Label("Validation", font="heading-sm")
    validated = bs.DateField(label="Required date", required=True)
    with bs.HStack(gap=8):
        bs.Button("Validate", on_click=lambda: validated.validate())

app.run()