Prepared Docs

Overview

TimePicker from @prepared911/ui-calendar is a thin wrapper around @prepared911/ui-core Input with type="time". It accepts HH:MM strings, exposes an optional tailIcon (defaults to a clock glyph), and renders a Label unless hideLabel is true. Use it for any same-day clock value—a meeting start, a reminder at 4pm, or the lower / upper bound of a TimeRangePicker.

For matched start / end pairs with optional maxRange enforcement, use TimeRangePicker (same package) which composes two TimePickers via TimeRangeInputs.

Start time

When to use

Single time-of-day values. Meeting start, reminder time, cutoff: native <input type="time"> gives platform-accessible pickers for free.
Bound inputs in TimeRangeInputs / TimeRangePicker. When the consuming surface renders a start / end pair, use the range variants rather than a handwritten pair of TimePickers.
Inside DateTimePicker / AdvancedDateTimeRangePicker. These compose TimePicker internally; you rarely need it standalone when the date is part of the value.

When not to use

Durations. Use a numeric Input or a dedicated duration control: "90 minutes" is not a time of day.
Date-plus-time. Use DateTimePicker so the two fields stay coordinated.
Query ranges across days. Use AdvancedDateTimeRangePicker.

Composition

TimePicker. Single field with id, value (HH:MM), onChange(string), optional label, hideLabel, and tailIcon.
TimeRangePicker. Self-contained start / end pair with optional maxRange (in hours). Default values are 00:00 and 23:59.
TimeRangeInputs. The primitive the range picker uses; reach for it when the parent already owns controlled strings and wants layout control (see CustomTimeRangePopoverContent in dispatch).

Customization

maxRange (range variants). Caps the span in hours; the component clamps the end when the start moves so the range can never exceed maxRange.
tailIcon. Override the default SVGAsset.Time when the field needs a product-specific glyph.
hideLabel. Drop the visible label when the surrounding layout supplies it externally; the field still uses label for the accessible name.

Best practices

Pair every TimePicker with a visible label or an external Label via id: native time inputs do not carry an implicit name.
Use the range variants for start / end pairs rather than stitching two TimePickers together; TimeRangeInputs enforces maxRange and keeps the en-dash separator consistent.
Keep HH:MM (24-hour) as the wire format; the native input handles locale display automatically.

Don't

Don't use TimePicker for a duration ("90 minutes") or a timestamp: it's a time of day, not an interval or an instant.
Don't hide the label and skip aria-label / label: screen readers need the accessible name.
Don't render two TimePickers bound to the same state; use a range variant.

Accessibility

Native <input type="time"> inherits the platform picker and keyboard semantics. The app is responsible for the visible label and for distinguishing start / end in speech when a range is rendered. See the Accessibility page for the full contract.

Date Time Picker: date + time when both matter.
Advanced Date Time Range Picker: range semantics across days.

Date Picker / Accessibility

Time Picker / API and Development

Overview

For matched start / end pairs with optional maxRange enforcement, use TimeRangePicker (same package) which composes two TimePickers via TimeRangeInputs.

Start time

When to use

Single time-of-day values. Meeting start, reminder time, cutoff: native <input type="time"> gives platform-accessible pickers for free.
Bound inputs in TimeRangeInputs / TimeRangePicker. When the consuming surface renders a start / end pair, use the range variants rather than a handwritten pair of TimePickers.
Inside DateTimePicker / AdvancedDateTimeRangePicker. These compose TimePicker internally; you rarely need it standalone when the date is part of the value.

When not to use

Durations. Use a numeric Input or a dedicated duration control: "90 minutes" is not a time of day.
Date-plus-time. Use DateTimePicker so the two fields stay coordinated.
Query ranges across days. Use AdvancedDateTimeRangePicker.

Composition

TimePicker. Single field with id, value (HH:MM), onChange(string), optional label, hideLabel, and tailIcon.
TimeRangePicker. Self-contained start / end pair with optional maxRange (in hours). Default values are 00:00 and 23:59.
TimeRangeInputs. The primitive the range picker uses; reach for it when the parent already owns controlled strings and wants layout control (see CustomTimeRangePopoverContent in dispatch).

Customization

maxRange (range variants). Caps the span in hours; the component clamps the end when the start moves so the range can never exceed maxRange.
tailIcon. Override the default SVGAsset.Time when the field needs a product-specific glyph.
hideLabel. Drop the visible label when the surrounding layout supplies it externally; the field still uses label for the accessible name.

Best practices

Pair every TimePicker with a visible label or an external Label via id: native time inputs do not carry an implicit name.
Use the range variants for start / end pairs rather than stitching two TimePickers together; TimeRangeInputs enforces maxRange and keeps the en-dash separator consistent.
Keep HH:MM (24-hour) as the wire format; the native input handles locale display automatically.

Don't

Don't use TimePicker for a duration ("90 minutes") or a timestamp: it's a time of day, not an interval or an instant.
Don't hide the label and skip aria-label / label: screen readers need the accessible name.
Don't render two TimePickers bound to the same state; use a range variant.