Time
TimePicker is a combobox-style input for picking a time from a list or typing it freely.
increment minutes apart between startHour and endHour. Type "9", "930", "9h30", "21:15" or "9:30 PM", then press Enter or leave the field to confirm; while you type, the list highlights the nearest time. onTimeChange(event, { selectedTime, selectedTimeText, errorType }) reports "invalid-input" / "out-of-start-bound" / "out-of-end-bound" so you can show the error through <Field>. The default hour cycle follows locale (vi-VN → 24-hour). Shares the input shell (fieldAppearanceClass) and the options with Combobox.Import
Install from npm, copy the source into your project with @yugen-ui/cli or the shadcn CLI, or import directly when working in this repo.
// npm install yugen-uiimport { TimePicker, Field, formatTime, parseTimeString, getTimesInRange } from "yugen-ui";Variants
Each tile is a standalone example: hover to copy, or press Code to see the source.
Working hours, 15-minute steps
startHour / endHour (endHour excluded) limit the list; typing "7" or "19:00" reports an out-of-range error.
minTime / maxTime & dateAnchor
Only the time part is compared; the returned time is set on the date of dateAnchor.
12-hour (SA / CH, AM / PM)
hourCycle="h12" uses the locale's day period labels; locale="en-US" defaults to 12-hour.
Size, appearance & disabled
small 24px, medium 32px, large 40px; appearance as in Input / Combobox.
Usage
- Wrap it in
<Field>and show a message based on theerrorTypefrom onTimeChange. - Pick an increment (15 / 30 minutes) that keeps the list short; other times can still be typed.
- Set startHour / endHour or minTime / maxTime instead of checking the value yourself after selection.
- Don't use TimePicker for durations ("2 hours 30 minutes"). Use SpinButton.
- Don't format times differently from one screen to another. Use hourCycle / locale.
Props
| Prop · Type | Default | Description |
|---|---|---|
| value / defaultValueDate | null | Default: — | Selected time (controlled / uncontrolled). |
| onTimeChange(event, { selectedTime, selectedTimeText, errorType? }) => void | Default: — | Called when an option is picked or typed text is confirmed (Enter / leaving the field). |
| onValueChange(value: Date | null) => void | Default: — | Called when the selected time changes; null when the field is cleared or the typed text is invalid. |
| incrementnumber | Default: 30 | Step between options (minutes). |
| startHour / endHournumber | Default: 0 / 24 | First hour (included) and last hour (excluded). |
| minTime / maxTimeDate | Default: — | Earliest / latest time (included, time part only). |
| hourCycle"h23" | "h12" | Default: from locale | 24-hour, or 12-hour with day period labels. |
| localestring | Default: "vi-VN" | Sets the default hourCycle and the SA/CH, AM/PM labels. |
| dateAnchorDate | Default: date of value / today | Date the returned time is set on. |
| formatDateToTimeString(date: Date) => string | Default: — | Custom display format. |
| appearance"outline" | "underline" | "filled-darker" | "filled-lighter" | Default: "outline" | Input shell style. |
| size"small" | "medium" | "large" | Default: "medium" | Height 24 / 32 / 40px. |
| disabled / required / id / aria-*— | Default: — | Passed by Field when wrapped in <Field>. |
| formatTime / parseTimeString / getTimesInRange / getTimeBoundsErrorhelper | Default: — | Pure functions to format a time, parse typed text, generate the time list and check the bounds. |
Messages
Text built into the component: labels, aria-labels, screen reader announcements.
English by default. Change it with the messages prop of YugenProvider, by the namespace below; messagesVi has the Vietnamese set. See Interface language.
messages.timePicker
| Key · Type | Default (English) | messagesVi |
|---|---|---|
| placeholderstring Placeholder của ô nhập. | Default (English)"Select a time…" | messagesVi"Chọn giờ…" |
| noOptionsstring Nội dung khi khoảng giờ rỗng. | Default (English)"No matching times" | messagesVi"Không có giờ phù hợp" |
| listLabelstring aria-label của danh sách giờ khi ô nhập không có nhãn riêng. | Default (English)"Select a time" | messagesVi"Chọn giờ" |
| closeListstring aria-label nút mũi tên khi danh sách đang mở. | Default (English)"Close time list" | messagesVi"Đóng danh sách giờ" |
| openListstring aria-label nút mũi tên khi danh sách đang đóng. | Default (English)"Open time list" | messagesVi"Mở danh sách giờ" |