Skip to content
Kimenpre-v1documentation home
Color scheme

ki-time-input

Use ki-time-input to collect a time of day. Set the surrounding lang to choose the hour cycle and the time shown in the field and suggestions. The public value and submitted form value use 24-hour HH:mm.

Theme for this example
Color scheme for this example
<ki-time-input
lang="en-GB"
label="Start time"
name="start"
value="09:30"
min="08:00"
max="18:00"
step="30"
help-text="Local office time"
time-zone="Europe/Madrid"
></ki-time-input>

Use min and max to set inclusive bounds within one day. step controls the interval between suggestions, starting at min or midnight. For example, the field above accepts a typed value of 09:17. A time zone appears in the help line and provides context for the wall-clock value.

Keyboard and validation

Provide a visible label. Down Arrow opens the suggestions without moving focus from the text field. Arrow keys navigate, Enter chooses a suggestion and Escape closes the list while preserving typed text. Validation errors appear after the person leaves the field or attempts to submit invalid data.

Customization

--ki-input-* tokens style the field. --ki-time-input-list-max-height limits the scrolling list. Customize selected slot colours through --ki-time-input-selected-bg and --ki-time-input-selected-fg. Decorative leading content goes in the start slot.

Listen for ki-change to consume event.detail.value after an edit is committed. In a form, add name and use required where applicable.

API reference

When to use: collect an exact time of day or offer regular appointment slots. Provide a visible label and set bounding times when the schedule is limited.

When not to use: durations, dates or timestamps. Pair with a date field when the day matters. Timezone conversion belongs to the application.

Properties & attributes

AttributePropertyTypeDefaultDescription
disableddisabledbooleanfalseDisables typing, suggestions and form participation.
error-texterrorTextstring | undefined–Validation message to show after blur or a blocked form submission.
help-texthelpTextstring | undefined–Guidance read with the field until a validation error replaces it.
invalid-time-textinvalidTimeTextstring'Enter a valid time within the allowed range.'Fallback validation message for invalid time syntax or bounds.
labellabelstring–Visible text naming the time field. Provide it for every use.
list-labellistLabelstring'Suggested times'Accessible name of the suggestion listbox.
maxmaxstring | undefined–Latest allowed wall-clock time in HH:mm, inclusive.
minminstring | undefined–Earliest allowed wall-clock time in HH:mm, inclusive.
namenamestring | undefined–Name under which the canonical time is submitted.
picker-labelpickerLabelstring'Choose time'Accessible name of the button that opens suggestions.
requiredrequiredbooleanfalseEmpty values block form submission when true.
stepstepnumber30Suggested slot interval in whole minutes. Typed times keep their exact minutes.
time-zonetimeZonestring | undefined–IANA timezone shown alongside help. Does not change wall-clock values.
valuevaluestring''Committed wall-clock time in HH:mm, or empty. The attribute sets the form reset value.

Events

EventDetail typeDescription
ki-changeCustomEvent<KiTimeInputChangeDetail>Emitted when a person commits a different canonical time or clears it.
changeEventNative-style composed event for a changed user commit.

Slots

SlotDescription
startOptional leading adornment, outside the input's accessible name.

CSS parts

PartDescription
errorPolite validation message that replaces help.
fieldField enclosure and anchor for the suggestions.
helpHelp and timezone describing the field.
inputEditable text combobox.
labelVisible label naming the editable combobox.
listboxScrollable list of suggested times.
optionIndividual suggested time.
triggerButton that opens suggested times.

CSS custom properties

The public styling contract of ki-time-input: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-density-control-offsetAdded to the block size of every scaled control and row (button, icon button, field, select, textarea, option, list item, tab). Components floor the result at ki.size.target-min.
--ki-density-space-scaleMultiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip).
--ki-density-target-minThe smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
--ki-focus-ring-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-offsetGap between a focusable component and its keyboard focus ring.
--ki-focus-ring-widthThickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once.
--ki-input-border-block-end-widthdimension used by the input component for border block end width.
--ki-input-border-block-start-widthdimension used by the input component for border block start width.
--ki-input-border-inline-end-widthdimension used by the input component for border inline end width.
--ki-input-border-inline-start-widthdimension used by the input component for border inline start width.
--ki-input-disabled-bgcolor used by the input component for disabled background.
--ki-input-disabled-bordercolor used by the input component for disabled border.
--ki-input-disabled-fgcolor used by the input component for disabled foreground (MarsUI disabled text Text/base_em; disabled cells are exempt from the contrast sweep).
--ki-input-disabled-label-fgcolor used by the input component for disabled label foreground.
--ki-input-focus-bgcolor used by the input component for focus background (MarsUI active state switches the fill to Surface/Special white / dark s2 — modeled with the scheme ladder s0).
--ki-input-focus-fgcolor used by the input component for focus foreground.
--ki-input-focus-label-fgcolor used by the input component for focus label foreground (MarsUI label is Text/med_em in every non-disabled state — active and danger included; the danger signal lives in the hint).
--ki-input-focus-ring-colorcolor used by the input component for focus ring color.
--ki-input-focus-ring-offsetdimension used by the input component for focus ring offset.
--ki-input-focus-ring-shadowshadow used by the input component for the focus ring glow (MarsUI Focus/primary: 3px spread ring at 20% — see ki.focus.primary. specs/002-ki-button/design-extraction.md §2.5 recorded 40%, having read the alpha off the Dark canvas mode, same double mechanism as ki-button: glow plus the opaque indicator).
--ki-input-focus-ring-widthdimension used by the input component for focus ring width.
--ki-input-font-sizedimension used by the input component for font size.
--ki-input-font-size-touchdimension used by the input component for the text a person types under a coarse primary pointer: 16px, under which Safari on iOS zooms the page into the focused field (spec 048). The onmars type scale has no 16px step.
--ki-input-font-weightfont weight used by the input component for font weight.
--ki-input-gapdimension used by the input component for gap.
--ki-input-heightdimension used by the input component for height (MarsUI Input_field md cell: min-height 40px; consume as min-block-size so the field can grow).
--ki-input-hover-bgcolor used by the input component for hover background (MarsUI hover = s2 + Black/3 overlay; s3 is the nearest token).
--ki-input-hover-bordercolor used by the input component for hover border.
--ki-input-hover-fgcolor used by the input component for hover foreground.
--ki-input-hover-label-fgcolor used by the input component for hover label foreground (MarsUI label is Text/med_em in every non-disabled state — active and danger included; the danger signal lives in the hint).
--ki-input-icon-sizedimension used by the input component for icon size.
--ki-input-invalid-bgcolor used by the input component for invalid background (MarsUI danger state keeps the white active fill; the ring and hint carry the signal).
--ki-input-invalid-bordercolor used by the input component for invalid border.
--ki-input-invalid-fgcolor used by the input component for invalid foreground.
--ki-input-invalid-label-fgcolor used by the input component for invalid label foreground (MarsUI label is Text/med_em in every non-disabled state — active and danger included; the danger signal lives in the hint).
--ki-input-invalid-ringshadow used by the input component for the persistent invalid ring (MarsUI Focus/danger: 3px danger-500 alpha spread; applied as box-shadow while :state(user-invalid)).
--ki-input-label-font-sizedimension used by the input component for label font size (MarsUI UI/Para/medium: body_1 13px).
--ki-input-label-font-weightfont weight used by the input component for label font weight.
--ki-input-label-gapdimension used by the input component for label gap.
--ki-input-label-line-heightdimension used by the input component for label line height (MarsUI line_height/para 20px).
--ki-input-label-padding-inlinedimension used by the input component for label padding inline (MarsUI Input_label row 2px inset aligning the label ink with the cell radius).
--ki-input-line-heightdimension used by the input component for line height.
--ki-input-padding-inlinedimension used by the input component for padding inline.
--ki-input-radiusdimension used by the input component for radius (MarsUI Radius/component/radius_md 10px, the md Input_cell binding; component ramp so personality modes reach it).
--ki-input-rest-bgcolor used by the input component for rest background (MarsUI Input_field rest fill Surface/s2: the fill identifies the field, not the outline).
--ki-input-rest-bordercolor used by the input component for rest border.
--ki-input-rest-fgcolor used by the input component for rest foreground.
--ki-input-rest-label-fgcolor used by the input component for rest label foreground (MarsUI label is Text/med_em in every non-disabled state — active and danger included; the danger signal lives in the hint).
--ki-motion-duration-fastFast interaction transition duration.
--ki-motion-easing-outDecelerating interaction transition easing curve.
--ki-text-danger-high-emsemantic color for text danger high em.
--ki-text-supportingSupporting text of an enabled control: field labels, placeholders, list secondary lines, quiet button labels and unselected tabs. A role, distinct from the med-em emphasis step it resolves to, so a mode can strengthen enabled supporting text without touching the disabled ink that also draws from med-em (directly, or through text.muted).
--ki-time-input-field-backdrop-filterComplete filter applied behind the surface.
--ki-time-input-field-bg-imageImage painted over the surface background.
--ki-time-input-list-backdrop-filterComplete filter applied behind the surface.
--ki-time-input-list-bgBackground of the suggested times list.
--ki-time-input-list-bg-imageImage painted over the surface background.
--ki-time-input-list-border-colorBorder colour of the suggested times list.
--ki-time-input-list-border-widthBorder width of the suggested times list.
--ki-time-input-list-fgText colour of the suggested times list.
--ki-time-input-list-max-heightMaximum block size of the scrolling suggestions.
--ki-time-input-list-paddingPadding on the inside edge of the suggested times list.
--ki-time-input-list-radiusCorner radius of the suggested times list.
--ki-time-input-list-shadowElevation of the suggested times list.
--ki-time-input-option-heightMinimum block size of a suggestion at standard density.
--ki-time-input-option-hover-bgBackground of a hovered suggestion.
--ki-time-input-option-hover-fgText colour of a hovered suggestion.
--ki-time-input-option-padding-inlineInline padding of a suggestion.
--ki-time-input-option-radiusCorner radius of a suggestion.
--ki-time-input-selected-bgBackground of the committed suggestion.
--ki-time-input-selected-fgText and check mark of the committed suggestion.
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-body-1semantic dimension for typography line height body 1.
--ki-typography-line-height-caption-2semantic dimension for typography line height caption 2.
--ki-typography-size-body-1semantic dimension for typography size body 1.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.
--ki-typography-weight-body-normalsemantic font weight for typography weight body normal.

Workshop

Open ki-time-input in Storybook