TimePicker
Use CTimePicker when people choose from a bounded schedule and the active Citry locale should format every visible time. It submits the same canonical HH:MM or HH:MM:SS string as a native time input.
Pick from regular intervals
The default fifteen-minute step produces a finite day list. Bounds limit the choices; a later minimum than maximum creates a wrapped overnight interval.
<c-CField required>
<c-fill name="label">Appointment time</c-fill>
<c-fill name="default"><c-CTimePicker name="appointment" min="09:00" max="17:00" /></c-fill>
</c-CField>
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class BasicTimePicker(Component):
template = """
<c-CField required>
<c-fill name="label">Appointment time</c-fill>
<c-fill name="description">Choose a fifteen-minute slot.</c-fill>
<c-fill name="default"><c-CTimePicker name="appointment" min="09:00" max="12:00" value="09:30" /></c-fill>
</c-CField>
"""
preview = BasicTimePicker()
preview # noqa: B018
Supply exact choices
Use options for irregular schedules or second precision. Options are checked, bounded, unique, and preserve server order. Structural option changes require a server rerender.
Show code
from datetime import time
from typing import Any
import citry_ui
from citry import Component, citry
from citry_ui import CTimePicker
citry.register_library(citry_ui)
class TimePickerOptions(Component):
def template_data(self, kwargs, slots) -> dict[str, Any]: # noqa: ANN001, ARG002
return {
"picker": CTimePicker(
name="departure", value=time(23, 5, 9), options=(time(23, 5, 9), "00:00:10", "12:30:45")
)
}
template = """
<section>
<h3>Irregular second-precision departures</h3>
{{ picker }}
</section>
"""
preview = TimePickerOptions()
preview # noqa: B018
Submit and reset
The hidden native time control remains the single Form transport and the no-JavaScript control. CField and CForm own shared state; the nested Listbox never becomes another form field.
Show code
import citry_ui
from citry import Component, citry
# ruff: noqa: E501 - embedded Citry templates remain readable
citry.register_library(citry_ui)
class TimePickerForm(Component):
template = """
<form x-data="{result:'Submit to inspect FormData'}" @submit.prevent="result=JSON.stringify(Object.fromEntries(new FormData($event.target)))">
<c-CField required>
<c-fill name="label">Start time</c-fill>
<c-fill name="default"><c-CTimePicker name="start" min="08:00" max="10:00" value="09:00" /></c-fill>
</c-CField>
<c-CButton type="submit">Submit</c-CButton>
<c-CButton type="reset" variant="outline">Reset</c-CButton>
<output x-text="result">Submit to inspect FormData</output>
</form>
"""
preview = TimePickerForm()
preview # noqa: B018
Control value and visibility
Client value and open are independently controlled while supplied. onValueChange and onOpenChange report requests; omission releases each channel at its latest committed value.
Show code
import citry_ui
from citry import Component, citry
# ruff: noqa: E501 - embedded Citry templates remain readable
citry.register_library(citry_ui)
class ControlledTimePicker(Component):
template = """
<section x-data="{value:'09:30',open:false,last:'No request yet'}" style="display:grid;gap:.75rem;max-width:24rem">
<c-CTimePicker min="09:00" max="11:00" $c-props="{value,open,onValueChange:(next,detail)=>{last=`${detail.source}: ${next}`;value=next},onOpenChange:(next)=>open=next}" />
<output x-text="last">No request yet</output>
</section>
"""
preview = ControlledTimePicker()
preview # noqa: B018
Switch locales in place
The server renders source-locale text first. Under a client-enabled c-i18n provider, the trigger, popup name, clear label, validity message, and generated option labels update when the locale changes. Canonical Form values do not.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class LocalizedTimePicker(Component):
template = """
<c-i18n tag="section" client>
<div style="display:flex;gap:.5rem;margin-block-end:1rem">
<c-CButton type="button" @click="$i18n.switchLocale('en-US')">English</c-CButton>
<c-CButton type="button" @click="$i18n.switchLocale('cs-CZ')">ΔeΕ‘tina</c-CButton>
</div>
<c-CTimePicker value="14:30" min="13:00" max="16:00" />
</c-i18n>
"""
preview = LocalizedTimePicker()
preview # noqa: B018
Literal placeholder, picker_label, change_label, clear_label, and unavailable_message overrides remain exactly application-owned and do not register catalog bindings.
Compare states and styles
Outline, filled, and plain variants combine with sm, md, and lg sizes. The picker inherits Popover collision handling, Listbox keyboard behavior, forced colors, logical direction, and reduced-motion handling.
Show code
import citry_ui
from citry import Component, citry
citry.register_library(citry_ui)
class TimePickerStates(Component):
template = """
<section style="display:grid;grid-template-columns:repeat(auto-fit,minmax(13rem,1fr));gap:1rem">
<c-CTimePicker value="09:00" min="08:00" max="12:00" />
<c-CTimePicker value="10:15" min="08:00" max="12:00" variant="filled" size="sm" />
<c-CTimePicker value="11:30" min="08:00" max="12:00" variant="plain" size="lg" readonly />
<c-CTimePicker value="12:00" min="08:00" max="12:00" invalid />
<c-CTimePicker value="08:30" min="08:00" max="12:00" disabled />
</section>
"""
preview = TimePickerStates()
preview # noqa: B018
API reference
Inputs
CTimePicker server inputs
Server inputs are passed in a template through <c-CTimePicker ... /> or in Python through CTimePicker(...).
| Input | Type | Default | Effect |
|---|---|---|---|
value | CTimePickerTime | None (CTimePickerTime) | None | Sets the initial and reset canonical time or empty value and must be an available option. |
name | str | None | None | Sets the native transport Form field name. |
form | str | None | None | Associates the native transport with an external Form ID. |
id | str | None | generated | Sets the public no-JavaScript input or enhanced Button ID and owned ID prefix. |
min | CTimePickerTime | None (CTimePickerTime) | None | Sets the inclusive first selectable time and may begin a wrapped interval. |
max | CTimePickerTime | None (CTimePickerTime) | None | Sets the inclusive last selectable time and may end a wrapped interval. |
step | int | 900 | Generates choices at an exact interval of at least 300 seconds when options is absent. |
options | Sequence[CTimePickerTime] | None | None | Supplies one through 288 unique exact choices in server order instead of generated intervals. |
required | bool | None | None | Enables native empty-value validity outside Field; Field owns it inside Field. |
disabled | bool | None | None | Blocks opening selection clearing and Form participation outside Field; Form disabledness also wins. |
readonly | bool | None | None | Keeps the picker focusable and submitted but blocks value changes. |
invalid | bool | None | None | Adds application invalid state to revealed native validity. |
clearable | bool | True | Shows a clear action for an optional non-empty writable value. |
dismissible | bool | True | Permits Escape outside and focus-outside close requests. |
placement | CPopoverPlacement (CPopoverPlacement) | "bottom-start" | Sets the preferred logical Popover placement. |
match_width | bool | True | Makes the Popover at least as wide as the visible control. |
placeholder | str | "Choose a time" | Supplies visible empty-state text when explicitly overridden. |
picker_label | str | "Choose time" | Names the popup Listbox and empty trigger when explicitly overridden. |
change_label | str | "Change time, {time}" | Formats a selected trigger name and must retain the time placeholder when explicitly overridden. |
clear_label | str | "Clear time" | Names the clear Button when explicitly overridden. |
unavailable_message | str | "Choose an available time." | Supplies native custom validity if a selected value is unavailable. |
variant | CTimePickerVariant (CTimePickerVariant) | "outline" | Selects outline filled or plain field treatment. |
size | CTimePickerSize (CTimePickerSize) | "md" | Selects coordinated control and text sizing. |
class_ | CClassValue | None (CClassValue) | None | Adds classes to the root and merges with attrs. |
style | CStyleValue | None (CStyleValue) | None | Adds styles to the root and merges with attrs. |
attrs | Mapping[str, object] | None | None | Adds copied allowed root attributes without replacing owned state identity or runtime markers. |
CTimePicker client inputs
Client inputs are passed in the browser through the $c-props="{ ... }" attribute on <c-CTimePicker />.
| Input | Type | Omitted behavior | Effect |
|---|---|---|---|
value | canonical string | null | Releases control at the latest committed value. | Controls selected and submitted time while supplied. |
open | boolean | null | Releases control at the latest committed visibility. | Controls popup visibility while supplied. |
required | boolean | Uses server or Field state. | Controls standalone required validity. |
disabled | boolean | Uses server or owner state. | Controls interaction and Form participation. |
readonly | boolean | Uses server or owner state. | Controls focusable nonmutable state. |
invalid | boolean | Uses server or Field state. | Controls application invalid state. |
clearable | boolean | Uses the server input. | Controls the optional clear action. |
dismissible | boolean | Uses the server input. | Controls passive popup dismissal. |
placement | CPopoverPlacement (CPopoverPlacement) | Uses the server input. | Controls preferred logical placement. |
matchWidth | boolean | Uses the server input. | Controls trigger-width matching. |
variant | CTimePickerVariant (CTimePickerVariant) | Uses the server input. | Controls field presentation. |
size | CTimePickerSize (CTimePickerSize) | Uses the server input. | Controls coordinated sizing. |
onValueChange | function | No semantic value callback. | Receives option clear native and reset value requests. |
onOpenChange | function | No semantic visibility callback. | Receives trigger selection dismissal reset and forced-close requests. |
Slots
-
Events
Component events are callback inputs supplied through $c-props. Native browser events remain available through Alpine @... attributes.
CTimePicker events
| Event | Signature | Trigger and timing | Detail | Controlled and cancellation behavior |
|---|---|---|---|---|
onValueChange | (value: string | null, detail: CTimePickerValueChangeDetail) => void (CTimePickerValueChangeDetail) | Listbox selection clear reset or native fallback editing requests another value. | {value, previousValue, controlled, source, sourceEvent} (CTimePickerValueChangeDetail) | Uncontrolled user commits emit native input/change; controlled requests wait for the owner. |
onOpenChange | (open: boolean, detail: CTimePickerOpenChangeDetail) => void (CTimePickerOpenChangeDetail) | Trigger selection clear reset Escape outside focus-outside native or forced layer changes request visibility. | {reason, controlled, forced, source} (CTimePickerOpenChangeDetail) | Uncontrolled requests commit before notification; controlled requests wait except forced safety closure. |
Methods
-
CSS
CSS variables to theme the components. Set them on an ancestor or the component itself.
CTimePicker CSS variables
Apply these variables to CTimePicker or one of its ancestors.
| Variable | Type | Purpose | Default |
|---|---|---|---|
--cui-time-picker-background | color | Visible control and clear background. | Canvas or variant-derived. |
--cui-time-picker-foreground | color | Text and icon color. | CanvasText |
--cui-time-picker-border-color | color | Visible control and clear boundary. | Mixed CanvasText. |
--cui-time-picker-invalid-border-color | color | Revealed invalid control boundary. | Theme error. |
--cui-time-picker-focus-color | color | Control and clear focus outline. | Highlight |
--cui-time-picker-radius | length | Visible control and clear corner radius. | 0.625rem |
--cui-time-picker-min-block-size | length | Minimum interactive control height. | 2.5rem |
--cui-time-picker-padding-inline | length | Visible control inline inset. | 0.75rem |
--cui-time-picker-gap | length | Visible value and icon gap. | 0.5rem |
--cui-time-picker-list-max-block-size | length | Maximum scrollable option-list height. | 18rem |
Attributes
HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.
CTimePicker attributes
| Attribute | Element | Type | Meaning |
|---|---|---|---|
data-empty | Root | present | absent | Marks no committed canonical value. |
data-open | Root | present | absent | Mirrors effective popup visibility. |
data-required | Root | present | absent | Mirrors effective requiredness. |
data-disabled | Root | present | absent | Mirrors effective disabledness. |
data-readonly | Root | present | absent | Mirrors effective readonly state. |
data-invalid | Root | present | absent | Mirrors application unavailable or revealed native invalidity. |
data-variant | Root | CTimePickerVariant (CTimePickerVariant) | Mirrors visual treatment. |
data-size | Root | CTimePickerSize (CTimePickerSize) | Mirrors coordinated sizing. |
data-enhanced | Root | present | absent | Marks completed custom control activation. |
Selectors
Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.
CTimePicker selectors
| Selector | Element | Purpose |
|---|---|---|
[data-citry-ui-part="time-picker"] | Root div | State reflection attrs and styling destination. |
[data-citry-ui-part="fallback-input"] | Native Time input | No-JavaScript control and enhanced Form reset validity transport. |
[data-citry-ui-part="enhanced-control"] | Layout div | Groups the Popover activator and optional clear action. |
[data-citry-ui-part="control"] | Native Button | Full-width popup activator and enhanced public focus target. |
[data-citry-ui-part="value"] | Span | Displays localized selected time or placeholder. |
[data-citry-ui-part="clear"] | Native Button | Requests an empty optional value. |
Interfaces
Aliases and data shapes referenced above.
Input type aliases
| Interface | Definition |
|---|---|
CTimePickerTime | time | str |
CTimePickerVariant | Literal["outline", "filled", "plain"] |
CTimePickerSize | Literal["sm", "md", "lg"] |
CTimePickerValueChangeSource | Literal["option", "clear", "reset", "native"] |
CPopoverPlacement | Literal["top-start", "top", "top-end", "bottom-start", "bottom", "bottom-end"] |
CClassValue | str | Mapping[str, bool] | Sequence[CClassValue] |
CStyleValue | str | Mapping[str, object] | Sequence[CStyleValue] |
CTimePickerValueChangeDetail
| Field | Type | Default | Meaning |
|---|---|---|---|
value | string | null | - | Requested selected canonical time or empty state. |
previousValue | string | null | - | Effective time before the request. |
controlled | boolean | - | Whether client value owns the commit. |
source | CTimePickerValueChangeSource (CTimePickerValueChangeSource) | - | Option clear reset or native cause. |
sourceEvent | object | null | - | Native interaction event when one exists. |
CTimePickerOpenChangeDetail
| Field | Type | Default | Meaning |
|---|---|---|---|
reason | trigger | selection | clear | reset | escape | outside | focus-outside | native | ancestor | modal | - | Exact request or forced-close cause. |
controlled | boolean | - | Whether client open owns ordinary visibility commits. |
forced | boolean | - | Whether ancestor or modal safety required closure. |
source | object | null | - | Associated browser source when one exists. |
Translation keys
Catalog keys used by this family. An explicit component input or slot listed in Override takes precedence over the catalog for that instance.
CTimePicker translation keys
| Key | Purpose | Variables | Override | Browser updates |
|---|---|---|---|---|
citry-ui-time-picker-placeholder | Displays the empty control value. | none | placeholder | Parent i18n subscription calls tr() because the same destination later displays formatted times. |
citry-ui-time-picker-label | Names the popup Listbox and empty trigger. | none | picker_label | $c-tr updates the stable title; parent subscription updates the dynamic trigger name. |
citry-ui-time-picker-change | Names a selected trigger. | `time: str` localized by a time display profile | change_label containing {time} | Parent i18n subscription recomputes the formatted value and calls tr(). |
citry-ui-time-picker-clear | Names the optional clear Button. | none | clear_label | $c-tr updates the stable aria-label destination. |
citry-ui-time-picker-unavailable | Supplies native custom validity when the value is unavailable. | none | unavailable_message | i18n.bind() updates the browser-owned validity message. |