Theme
Version
GitHub PyPI Discord
On this page

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>
Pick an appointment time
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.

Supply exact time choices
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.

Submit and reset a time picker
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.

Control time and popup state
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.

Format time choices by locale
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.

Compare TimePicker states
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(...).

InputTypeDefaultEffect
valueCTimePickerTime | None (CTimePickerTime)NoneSets the initial and reset canonical time or empty value and must be an available option.
namestr | NoneNoneSets the native transport Form field name.
formstr | NoneNoneAssociates the native transport with an external Form ID.
idstr | NonegeneratedSets the public no-JavaScript input or enhanced Button ID and owned ID prefix.
minCTimePickerTime | None (CTimePickerTime)NoneSets the inclusive first selectable time and may begin a wrapped interval.
maxCTimePickerTime | None (CTimePickerTime)NoneSets the inclusive last selectable time and may end a wrapped interval.
stepint900Generates choices at an exact interval of at least 300 seconds when options is absent.
optionsSequence[CTimePickerTime] | NoneNoneSupplies one through 288 unique exact choices in server order instead of generated intervals.
requiredbool | NoneNoneEnables native empty-value validity outside Field; Field owns it inside Field.
disabledbool | NoneNoneBlocks opening selection clearing and Form participation outside Field; Form disabledness also wins.
readonlybool | NoneNoneKeeps the picker focusable and submitted but blocks value changes.
invalidbool | NoneNoneAdds application invalid state to revealed native validity.
clearableboolTrueShows a clear action for an optional non-empty writable value.
dismissibleboolTruePermits Escape outside and focus-outside close requests.
placementCPopoverPlacement (CPopoverPlacement)"bottom-start"Sets the preferred logical Popover placement.
match_widthboolTrueMakes the Popover at least as wide as the visible control.
placeholderstr"Choose a time"Supplies visible empty-state text when explicitly overridden.
picker_labelstr"Choose time"Names the popup Listbox and empty trigger when explicitly overridden.
change_labelstr"Change time, {time}"Formats a selected trigger name and must retain the time placeholder when explicitly overridden.
clear_labelstr"Clear time"Names the clear Button when explicitly overridden.
unavailable_messagestr"Choose an available time."Supplies native custom validity if a selected value is unavailable.
variantCTimePickerVariant (CTimePickerVariant)"outline"Selects outline filled or plain field treatment.
sizeCTimePickerSize (CTimePickerSize)"md"Selects coordinated control and text sizing.
class_CClassValue | None (CClassValue)NoneAdds classes to the root and merges with attrs.
styleCStyleValue | None (CStyleValue)NoneAdds styles to the root and merges with attrs.
attrsMapping[str, object] | NoneNoneAdds 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 />.

InputTypeOmitted behaviorEffect
valuecanonical string | nullReleases control at the latest committed value.Controls selected and submitted time while supplied.
openboolean | nullReleases control at the latest committed visibility.Controls popup visibility while supplied.
requiredbooleanUses server or Field state.Controls standalone required validity.
disabledbooleanUses server or owner state.Controls interaction and Form participation.
readonlybooleanUses server or owner state.Controls focusable nonmutable state.
invalidbooleanUses server or Field state.Controls application invalid state.
clearablebooleanUses the server input.Controls the optional clear action.
dismissiblebooleanUses the server input.Controls passive popup dismissal.
placementCPopoverPlacement (CPopoverPlacement)Uses the server input.Controls preferred logical placement.
matchWidthbooleanUses the server input.Controls trigger-width matching.
variantCTimePickerVariant (CTimePickerVariant)Uses the server input.Controls field presentation.
sizeCTimePickerSize (CTimePickerSize)Uses the server input.Controls coordinated sizing.
onValueChangefunctionNo semantic value callback.Receives option clear native and reset value requests.
onOpenChangefunctionNo 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

EventSignatureTrigger and timingDetailControlled 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.

VariableTypePurposeDefault
--cui-time-picker-backgroundcolorVisible control and clear background.Canvas or variant-derived.
--cui-time-picker-foregroundcolorText and icon color.CanvasText
--cui-time-picker-border-colorcolorVisible control and clear boundary.Mixed CanvasText.
--cui-time-picker-invalid-border-colorcolorRevealed invalid control boundary.Theme error.
--cui-time-picker-focus-colorcolorControl and clear focus outline.Highlight
--cui-time-picker-radiuslengthVisible control and clear corner radius.0.625rem
--cui-time-picker-min-block-sizelengthMinimum interactive control height.2.5rem
--cui-time-picker-padding-inlinelengthVisible control inline inset.0.75rem
--cui-time-picker-gaplengthVisible value and icon gap.0.5rem
--cui-time-picker-list-max-block-sizelengthMaximum 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

AttributeElementTypeMeaning
data-emptyRootpresent | absentMarks no committed canonical value.
data-openRootpresent | absentMirrors effective popup visibility.
data-requiredRootpresent | absentMirrors effective requiredness.
data-disabledRootpresent | absentMirrors effective disabledness.
data-readonlyRootpresent | absentMirrors effective readonly state.
data-invalidRootpresent | absentMirrors application unavailable or revealed native invalidity.
data-variantRootCTimePickerVariant (CTimePickerVariant)Mirrors visual treatment.
data-sizeRootCTimePickerSize (CTimePickerSize)Mirrors coordinated sizing.
data-enhancedRootpresent | absentMarks completed custom control activation.

Selectors

Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.

CTimePicker selectors

SelectorElementPurpose
[data-citry-ui-part="time-picker"]Root divState reflection attrs and styling destination.
[data-citry-ui-part="fallback-input"]Native Time inputNo-JavaScript control and enhanced Form reset validity transport.
[data-citry-ui-part="enhanced-control"]Layout divGroups the Popover activator and optional clear action.
[data-citry-ui-part="control"]Native ButtonFull-width popup activator and enhanced public focus target.
[data-citry-ui-part="value"]SpanDisplays localized selected time or placeholder.
[data-citry-ui-part="clear"]Native ButtonRequests an empty optional value.

Interfaces

Aliases and data shapes referenced above.

Input type aliases

InterfaceDefinition
CTimePickerTimetime | str
CTimePickerVariantLiteral["outline", "filled", "plain"]
CTimePickerSizeLiteral["sm", "md", "lg"]
CTimePickerValueChangeSourceLiteral["option", "clear", "reset", "native"]
CPopoverPlacementLiteral["top-start", "top", "top-end", "bottom-start", "bottom", "bottom-end"]
CClassValuestr | Mapping[str, bool] | Sequence[CClassValue]
CStyleValuestr | Mapping[str, object] | Sequence[CStyleValue]

CTimePickerValueChangeDetail

FieldTypeDefaultMeaning
valuestring | null-Requested selected canonical time or empty state.
previousValuestring | null-Effective time before the request.
controlledboolean-Whether client value owns the commit.
sourceCTimePickerValueChangeSource (CTimePickerValueChangeSource)-Option clear reset or native cause.
sourceEventobject | null-Native interaction event when one exists.

CTimePickerOpenChangeDetail

FieldTypeDefaultMeaning
reasontrigger | selection | clear | reset | escape | outside | focus-outside | native | ancestor | modal-Exact request or forced-close cause.
controlledboolean-Whether client open owns ordinary visibility commits.
forcedboolean-Whether ancestor or modal safety required closure.
sourceobject | 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

KeyPurposeVariablesOverrideBrowser updates
citry-ui-time-picker-placeholderDisplays the empty control value.noneplaceholderParent i18n subscription calls tr() because the same destination later displays formatted times.
citry-ui-time-picker-labelNames the popup Listbox and empty trigger.nonepicker_label$c-tr updates the stable title; parent subscription updates the dynamic trigger name.
citry-ui-time-picker-changeNames a selected trigger.`time: str` localized by a time display profilechange_label containing {time}Parent i18n subscription recomputes the formatted value and calls tr().
citry-ui-time-picker-clearNames the optional clear Button.noneclear_label$c-tr updates the stable aria-label destination.
citry-ui-time-picker-unavailableSupplies native custom validity when the value is unavailable.noneunavailable_messagei18n.bind() updates the browser-owned validity message.