TimeField

A time input field with a searchable dropdown list of time intervals. The user can type a custom time or select from the dropdown.

Usage

Basic usage

bs.TimeField(label="Select a time")

Display formats

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

now = datetime.time(14, 30)
bs.TimeField(value=now, value_format="shortTime")   # 2:30 PM
bs.TimeField(value=now, value_format="HH:mm")       # 14:30
bs.TimeField(value=now, value_format="HH:mm:ss")    # 14:30:00
bs.TimeField(value=now, value_format="h:mm a")      # 2:30 PM

Dropdown interval

The interval= parameter sets the spacing between entries in the dropdown.

bs.TimeField(interval=15)   # every 15 minutes
bs.TimeField(interval=30)   # every 30 minutes (default)
bs.TimeField(interval=60)   # hourly

Time range constraints

Use min_time= and max_time= to limit which times appear in the dropdown.

import datetime

bs.TimeField(
    label="Appointment time",
    message="Available 9 AM – 5 PM.",
    min_time=datetime.time(9, 0),
    max_time=datetime.time(17, 0),
    interval=30,
)

Reactive binding

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

time_sig = bs.Signal("")
bs.TimeField(label="Pick a time", textsignal=time_sig)
bs.Label(textsignal=time_sig, accent="secondary")

Handling changes

on_change() fires whenever the time value changes — whether by typing, dropdown selection, or value= assignment.

tf = bs.TimeField(label="Start time")
tf.on_change(lambda e: print("Selected:", tf.value))

States

bs.TimeField(value=now, label="Normal")
bs.TimeField(value=now, label="Read only", read_only=True)
bs.TimeField(value=now, 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

• DateField — date input with calendar picker

API

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

TimeField

A time-input field with a searchable dropdown of time intervals.

Full Example

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

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

    # Time format presets
    bs.Label("Display Formats", font="heading-sm")
    now = datetime.time(14, 30)
    bs.TimeField(value=now, label="Short time (default)", value_format="shortTime")
    bs.TimeField(value=now, label="24-hour",              value_format="HH:mm")
    bs.TimeField(value=now, label="24-hour with seconds",  value_format="HH:mm:ss")

    # Dropdown interval
    bs.Label("Dropdown Interval", font="heading-sm")
    bs.TimeField(value=now, label="15-minute intervals", interval=15)
    bs.TimeField(value=now, label="60-minute intervals", interval=60)

    # Time range constraints
    bs.Label("Business Hours", font="heading-sm")
    bs.TimeField(
        value=datetime.time(9, 0),
        label="Appointment time",
        message="Available Monday – Friday, 9 AM – 5 PM.",
        min_time=datetime.time(9, 0),
        max_time=datetime.time(17, 0),
        interval=30,
    )

    # Reactive binding
    bs.Label("Reactive Binding", font="heading-sm")
    time_sig = bs.Signal("")
    bs.TimeField(label="Pick a time", textsignal=time_sig)
    bs.Label(textsignal=time_sig, accent="secondary")

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

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

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

app.run()