TimeInput

Use CTimeInput when a browser-native time editor is the shortest path. It preserves platform keyboard, touch picker, validation, reset, and Form behavior while keeping the application value locale-neutral.

Collect one time

Compose the control in CField for its visible label, description, error, and shared state. A standalone input needs an accessible name through attrs or an external native label.

<c-CField required>
  <c-fill name="label">Start time</c-fill>
  <c-fill name="default"><c-CTimeInput name="start" /></c-fill>
</c-CField>

Collect one time

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class BasicTimeInput(Component):
    template = """
      <c-CField required>
        <c-fill name="label">Start time</c-fill>
        <c-fill name="description">Choose when the session starts.</c-fill>
        <c-fill name="default"><c-CTimeInput name="start" /></c-fill>
      </c-CField>
    """


preview = BasicTimeInput()
preview  # noqa: B018

Python composition accepts an exact zone-free datetime.time. Localized text, offset-aware times, fractional seconds, and noncanonical strings are rejected.

Constrain a periodic time range

min, max, and positive integer step map to native time constraints. A minimum later than the maximum deliberately expresses a wrapped interval such as 23:00 through 02:00.

Constrain a native time

Show code

import citry_ui
from citry import Component, citry

# ruff: noqa: E501 - embedded Citry templates remain readable

citry.register_library(citry_ui)


class TimeInputConstraints(Component):
    template = """
      <section style="display:grid;gap:1rem;max-width:22rem">
        <label>Office appointment <c-CTimeInput name="office" min="09:00" max="17:00" c-step="900" value="09:30" /></label>
        <label>Overnight window <c-CTimeInput name="overnight" min="23:00" max="02:00" value="23:30" /></label>
      </section>
    """


preview = TimeInputConstraints()
preview  # noqa: B018

The server must validate submitted values again; the component never silently clamps or rounds.

Use Forms and client control

name contributes exactly one canonical value. Disabled inputs are omitted; readonly inputs remain submitted. Client value accepts a canonical string or null, and omission releases control at the latest accepted value.

Submit and reset a time

Show code

import citry_ui
from citry import Component, citry

# ruff: noqa: E501 - embedded Citry templates remain readable

citry.register_library(citry_ui)


class TimeInputForm(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">Delivery time</c-fill>
          <c-fill name="default"><c-CTimeInput name="delivery" value="14:30" /></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 = TimeInputForm()
preview  # noqa: B018

Understand locale behavior

The DOM value and FormData stay HH:MM or HH:MM:SS; the browser chooses the visible segment order, hour cycle, picker, and native validation prose. Use CTimePicker when Citry i18n must own the visible choice labels.

Compare states and styles

Outline, filled, and plain variants combine with sm, md, and lg sizes. Public variables style the native control without replacing its semantics.

Compare TimeInput states

Show code

import citry_ui
from citry import Component, citry

citry.register_library(citry_ui)


class TimeInputStates(Component):
    template = """
      <section style="display:grid;grid-template-columns:repeat(auto-fit,minmax(12rem,1fr));gap:1rem">
        <label>Outline <c-CTimeInput value="09:00" /></label>
        <label>Filled <c-CTimeInput value="10:15" variant="filled" size="sm" /></label>
        <label>Plain readonly <c-CTimeInput value="11:30" variant="plain" size="lg" readonly /></label>
        <label>Invalid <c-CTimeInput value="12:45" invalid /></label>
        <label>Disabled <c-CTimeInput value="13:00" disabled /></label>
      </section>
    """


preview = TimeInputStates()
preview  # noqa: B018

CTimeInput owns no translation keys. Labels and errors belong to the application; the platform owns the native editor and its prose.

API reference

Inputs

CTimeInput server inputs

Server inputs are passed in a template through <c-CTimeInput ... /> or in Python through CTimeInput(...).

Input	Type	Default	Effect
`value`	`CTimeInputValue \| None` (`CTimeInputValue`)	`None`	Sets the initial and reset canonical time or empty value.
`name`	`str \| None`	`None`	Sets the native Form field name.
`form`	`str \| None`	`None`	Associates the input with an external native Form ID.
`id`	`str \| None`	generated	Sets the public native input ID.
`min`	`CTimeInputValue \| None` (`CTimeInputValue`)	`None`	Sets the inclusive native minimum and may start a wrapped range.
`max`	`CTimeInputValue \| None` (`CTimeInputValue`)	`None`	Sets the inclusive native maximum and may end a wrapped range.
`step`	`int`	`60`	Sets the exact positive native step in seconds.
`required`	`bool \| None`	`None`	Enables native empty-value validity outside Field; Field owns it inside Field.
`disabled`	`bool \| None`	`None`	Blocks interaction and Form participation outside Field; Form disabledness also wins.
`readonly`	`bool \| None`	`None`	Keeps a focusable submitted value while blocking native edits.
`invalid`	`bool \| None`	`None`	Adds application invalid state to revealed native validity.
`autocomplete`	`str \| None`	`None`	Sets a native autofill hint.
`variant`	`"outline" \| "filled" \| "plain"` (`CTimeInputVariant`)	`"outline"`	Selects outer native-control treatment.
`size`	`"sm" \| "md" \| "lg"` (`CTimeInputSize`)	`"md"`	Selects coordinated sizing.
`class_`	`CClassValue \| None` (`CClassValue`)	`None`	Adds classes to the native root and merges with attrs.
`style`	`CStyleValue \| None` (`CStyleValue`)	`None`	Adds styles to the native root and merges with attrs.
`attrs`	`Mapping[str, object] \| None`	`None`	Adds copied allowed native attributes without replacing owned identity state constraints or runtime markers.

CTimeInput client inputs

Client inputs are passed in the browser through the $c-props="{ ... }" attribute on <c-CTimeInput />.

Input	Type	Omitted behavior	Effect
`value`	`canonical string \| null`	Releases control at the latest accepted value.	Controls the exact native value while supplied.
`min`	`canonical string \| null`	Uses the server minimum.	Replaces or removes the inclusive minimum.
`max`	`canonical string \| null`	Uses the server maximum.	Replaces or removes the inclusive maximum.
`step`	`positive integer`	Uses the server step.	Replaces the native seconds step.
`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.
`variant`	`"outline" \| "filled" \| "plain"` (`CTimeInputVariant`)	Uses the server input.	Controls presentation.
`size`	`"sm" \| "md" \| "lg"` (`CTimeInputSize`)	Uses the server input.	Controls coordinated sizing.

Variable	Type	Purpose	Default
`--cui-time-input-background`	`color`	Native control background.	`Canvas`
`--cui-time-input-foreground`	`color`	Native time text and indicator foreground.	`CanvasText`
`--cui-time-input-border-color`	`color`	Resting border.	`Mixed CanvasText.`
`--cui-time-input-hover-border-color`	`color`	Hover border.	`Stronger mixed CanvasText.`
`--cui-time-input-focus-color`	`color`	Focus border and outline.	`Highlight`
`--cui-time-input-invalid-border-color`	`color`	Invalid border.	`Theme error.`
`--cui-time-input-disabled-background`	`color`	Disabled background.	`Muted Canvas.`
`--cui-time-input-radius`	`length`	Outer corner radius.	`0.5rem`
`--cui-time-input-height`	`length`	Minimum block size.	`2.5rem`
`--cui-time-input-inline-padding`	`length`	Logical inline inset.	`0.75rem`
`--cui-time-input-block-padding`	`length`	Logical block inset.	`0.5rem`
`--cui-time-input-font-size`	`length`	Time text size.	`1rem`
`--cui-time-input-min-inline-size`	`length`	Preferred minimum width before container clamping.	`10rem`

Attributes

HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.

CTimeInput attributes

Attribute	Element	Type	Meaning
`type`	Native root input	`"time"`	Selects browser-owned wall-clock editing and picker behavior.
`value`	Native root input	`canonical time \| absent`	Carries the initial and reset time.
`min`	Native root input	`canonical time \| absent`	Sets inclusive native minimum validity.
`max`	Native root input	`canonical time \| absent`	Sets inclusive native maximum validity.
`step`	Native root input	`positive integer`	Sets the seconds step grid.
`aria-invalid`	Native root input	`"true" \| absent`	Mirrors application or revealed native invalidity.
`data-empty`	Native root input	`present \| absent`	Mirrors an empty canonical value.
`data-required`	Native root input	`present \| absent`	Mirrors effective requiredness.
`data-disabled`	Native root input	`present \| absent`	Mirrors effective disabledness.
`data-readonly`	Native root input	`present \| absent`	Mirrors effective readonly state.
`data-invalid`	Native root input	`present \| absent`	Mirrors application or revealed native invalidity.
`data-variant`	Native root input	`CTimeInputVariant` (`CTimeInputVariant`)	Mirrors visual treatment.
`data-size`	Native root input	`CTimeInputSize` (`CTimeInputSize`)	Mirrors coordinated sizing.

Selectors

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

CTimeInput selectors

Selector	Element	Purpose
`[data-citry-ui-part="time-input"]`	Native root input	Stable styling state Form focus event and attrs destination.

Interfaces

Aliases and data shapes referenced above.

Input type aliases

Interface	Definition
`CTimeInputValue`	`time \| str`
`CTimeInputVariant`	`Literal["outline", "filled", "plain"]`
`CTimeInputSize`	`Literal["sm", "md", "lg"]`
`CClassValue`	`str \| Mapping[str, bool] \| Sequence[CClassValue]`
`CStyleValue`	`str \| Mapping[str, object] \| Sequence[CStyleValue]`

TimeInput

Collect one time

Constrain a periodic time range

Use Forms and client control

Understand locale behavior

Compare states and styles

API reference

Inputs

CTimeInput server inputs

CTimeInput client inputs

Slots

Events

Methods

CSS

CTimeInput CSS variables

Attributes

CTimeInput attributes

Selectors

CTimeInput selectors

Interfaces

Input type aliases

Translation keys