Coral is a thoroughly developed design system widely adopted by developers and designers for creating beautiful and user-friendly Sea internal products.
Copyright © 2018-2025 Sea Labs
TimePicker
Designer doc
Select hour and minute in Dayjs format with TimePicker component.
Example
Basic Usage
View code
Hour and Minute Steps
By default, TimePicker shows all hours and every minute. You can customize using hourStep and minuteStep props.
View code
Disabling Times
You can disable some hours and minutes using isHourDisabled and isMinuteDisabled props accepting function returning boolean.
TimePicker will try to find the best hours, minutes, and seconds combination when one of them is initially selected. This will ensure the value won’t fall into disabled times.
View code
Similar logic is also applied when the minute being selected is disabled when a certain hour is selected.
Disabling Minutes on Certain Hours
Note that when specifying disabled minutes based on hour, it’s better to use hour value from isMinuteDisabled second parameter, rather than from your possibly hoisted selected hour state. Otherwise, TimePicker won’t be able to accurately validate when an hour, minute, or second is selected.
Below is an example for “Select time between 9.30 and 19.15”.
View code
Formatting Time
timeFormat prop can be used to customize input text value based on current value. This prob is also used to parse time from text and default placeholder.
View code
Using parseTime and displayTime
You can also pass your custom input parsing and display function. For example, this TimePicker will be able to translate ‘Now’, ‘Next Hour’, and ‘Next Period’
View code
Customizing Popup
Popup Placements
View code
Adding Seconds
In order to do so, you need to override default popupElement’s children and so on. This way, you can also reorder or omit the hour options. Similar to hours and minutes, you can specify isSecondDisabled and secondStep for custom second options.
View code
Translating “Hour”, “Minute”, etc
You can specify header prop on TimePickerHours, TimePickerMinutes, and TimePickerSeconds components.
View code
To make it reusable, you can wrap the components and reexpose them.
View code
Customizing Input
TimePickerInput is TextField with a certain default props and behaviours. You can pass similar props as TextField‘s.
View code
More Customizations
In some cases you may want to add more option list. To ensure keyboard navigation still works nicely with the custom one, you can use TimePickerList inside TimePickerListContainer.
View code
Controlling states from external components
You can also use external components (e.g. Button) to control the states from outside.
View code
InlineTimePicker Component
Aside from full-fleged TimePicker component, which includes TimePickerInput and TimePickerPopup, you can also use InlineTimePicker component. This component has less opinionated structure, where you can also integrate it with other components like DatePicker.
View code
DatePicker Integration
Below is an example of combining date and time values. By default, DatePicker will close the popup when a date is selected, so you need to omit this behaviour by specifying closeOnClick={false} on DatePickerDateCell like in example below.
View code
Accessibility
For hours, minutes, seconds, and general TimePickerList, it has role of spinbutton, where pressing ArrowUp and ArrowDown go through the enabled options. Pressing ArrowLeft and ArrowRight will navigate through the lists.
Pressing ArrowDown, Enter, and Escape will subsequently open and close the popup and autofocus to the first spinbutton.
References
- Ant Design: https://ant.design/components/time-picker/
- Spin Button Example: https://www.w3.org/WAI/ARIA/apg/example-index/spinbutton/datepicker-spinbuttons.html
API
InlineTimePicker
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| hourStep | number | 1 | |
| initialValue | Dayjs | ||
| isHourDisabled | (hour: number) => boolean | () => false | |
| isMinuteDisabled | (minute: number, hour: number) => boolean | () => false | |
| isSecondDisabled | (second: number, minute: number, hour: number) => boolean | () => false | |
| minuteStep | number | 1 | |
| now | Dayjs | dayjs() | |
| onChange | (value: Dayjs) => void | ||
| secondStep | number | 1 | |
| value | Dayjs |
TimePicker
| Prop name | Type | Default | Description |
|---|---|---|---|
| disabled | boolean | Disable input, time selection, and opening popup. | |
| displayTime | (value: Dayjs) => string | (value: Dayjs | null) => (value ? value.format(timeFormat) : '') | Callback to convert value to inputValue |
| hourStep | number | 1 | |
| initialIsOpen | boolean | Uncontrolled of popup open state. | |
| initialValue | Dayjs | ||
| inputElement | ReactElement<any, any> | <TimePickerInput /> | Customizing input. Normally, how you use this prop is passing DatePickerInput with some additional props. |
| inputValue | string | Controlled input value. You can think of this prop as text representation of value using dateFormat. | |
| isHourDisabled | (hour: number) => boolean | () => false | Whether a certain time cannot be selected. This prop is not only used to disable times on the spinbuttons, but also for input not to trigger selection when input is a valid time but disabled. |
| isMinuteDisabled | (minute: number, hour: number) => boolean | () => false | |
| isOpen | boolean | Controlled of popup open state. | |
| isSecondDisabled | (second: number, minute: number, hour: number) => boolean | () => false | |
| minuteStep | number | 1 | |
| now | Dayjs | dayjs() | Useful for consistent testing, default to dayjs() |
| onChange | (value: Dayjs) => void | ||
| onInputChange | (inputValue: string) => void | Callback when input value changes.Generally, it's triggered by: (1) Typing on the input. (2) Blur or clicking away from input, which will reset to selected value. (3) A time is selected. | |
| onIsOpenChange | (isOpen: boolean) => void | Callback when popup open state changes.The event that triggers opening the popup is the same as Balloon component's - either click or keyboard arrow down. Closing is triggered when a date is selected. | |
| parseTime | (inputValue: string) => Dayjs | (value: string) => dayjs(value, timeFormat) | Callback to convert inputValue to value |
| popupElement | ReactElement<any, any> | <TimePickerPopup /> | Customizing popup. Normally, how you use this prop is passing DatePickerPopup with some additional props. |
| secondStep | number | 1 | |
| timeFormat | string | HH:mm | Dayjs format to display from selected time, and parse input to autoselect time when the parse is valid. |
| value | Dayjs |
TimePickerHours
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| header | ReactNode | Hour | |
| headerProps | HeaderProps | ||
| index | number | ||
| scrollerProps | TimePickerScrollerProps & { ref?: Ref<HTMLDivElement>; } |
TimePickerIcon
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| clearable | boolean | ||
| colorType | ColorTypes | Set color based on theme. If color is specified, that prop is used instead of this. | |
| disabled | boolean | Equivalent to button's disabled property. | |
| keyboardClickKeys | string[] | ||
| loading | boolean | ||
| onBlur | FocusEventHandler<HTMLDivElement> | ||
| onClick | MouseEventHandler<HTMLDivElement> | ||
| onKeyDown | KeyboardEventHandler<HTMLDivElement> | ||
| onKeyUp | KeyboardEventHandler<HTMLDivElement> | ||
| onMouseDown | MouseEventHandler<HTMLDivElement> | ||
| onMouseLeave | MouseEventHandler<HTMLDivElement> | ||
| onMouseUp | MouseEventHandler<HTMLDivElement> | ||
| onRelease | EventHandler<SyntheticEvent<HTMLDivElement, Event>> | Callback that's triggered after click i.e. mouseup and keyup of enter or space. | |
| onTouchEnd | TouchEventHandler<HTMLDivElement> | ||
| onTouchStart | TouchEventHandler<HTMLDivElement> | ||
| radius | string | ||
| size | IconButtonSizes | ||
| tooltip | ReactNode | ||
| tooltipProps | Omit<TooltipProps, "title" | "children"> | ||
| variant | IconButtonVariants |
TimePickerInput
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| autoComplete | "on" | "off" | "nope" | ||
| defaultValue | string | @deprecated use initialValue | |
| disabled | boolean | ||
| fullWidth | boolean | width: 100% is too troublesome to handle with custom css because of the nesting | |
| initialValue | string | ||
| invalid | boolean | ||
| leftElement | ReactNode | ||
| leftElementContainerProps | HTMLAttributes<HTMLDivElement> & { ref?: MutableRefObject<HTMLDivElement>; } | ||
| onChange | (e: ChangeEvent<HTMLInputElement>) => void | ||
| onTextChange | (val: string) => void | ||
| placeholder | ReactNode | ||
| readOnly | boolean | ||
| rightElement | ReactNode | <TimePickerIcon /> | |
| rightElementContainerProps | HTMLAttributes<HTMLDivElement> & { ref?: MutableRefObject<HTMLDivElement>; } | ||
| type | "number" | "text" | "password" | ||
| value | string | ||
| wrapperProps | WrapperProps |
TimePickerList
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| header | ReactNode | ||
| headerProps | HeaderProps | ||
| index | number | ||
| initialValue | OptionValue | ||
| onChange | (value: OptionValue) => void | ||
| scrollerProps | TimePickerScrollerProps & { ref?: Ref<HTMLDivElement>; } | ||
| value | OptionValue |
TimePickerListContainer
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. |
TimePickerMinutes
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| header | ReactNode | Minute | |
| headerProps | HeaderProps | ||
| index | number | ||
| scrollerProps | TimePickerScrollerProps & { ref?: Ref<HTMLDivElement>; } |
TimePickerOption
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| disabled | boolean | Equivalent to button's disabled property. | |
| index | number | ||
| keyboardClickKeys | string[] | ||
| onBlur | FocusEventHandler<HTMLDivElement> | ||
| onClick | MouseEventHandler<HTMLDivElement> | ||
| onKeyDown | KeyboardEventHandler<HTMLDivElement> | ||
| onKeyUp | KeyboardEventHandler<HTMLDivElement> | ||
| onMouseDown | MouseEventHandler<HTMLDivElement> | ||
| onMouseLeave | MouseEventHandler<HTMLDivElement> | ||
| onMouseUp | MouseEventHandler<HTMLDivElement> | ||
| onRelease | EventHandler<SyntheticEvent<HTMLDivElement, Event>> | Callback that's triggered after click i.e. mouseup and keyup of enter or space. | |
| onTouchEnd | TouchEventHandler<HTMLDivElement> | ||
| onTouchStart | TouchEventHandler<HTMLDivElement> | ||
| value | OptionValue |
TimePickerPopup
| Prop name | Type | Default | Description |
|---|---|---|---|
| arrow | ArrowProps | ||
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| container | HTMLElement | ||
| focusOnOpen | boolean | ||
| immediate | boolean | ||
| offset | [number, number] | ||
| onComponentBlur | () => void | Callback function that will be called when the whole Balloon component is blurred. | |
| placement | Placements | bottom-start | |
| popperOptions | PopperPopperOptions | Options for Popper.js instance | |
| popperUpdateKey | string | ||
| shouldKeyDownReturn | (e: KeyboardEvent<HTMLDivElement>) => boolean | ||
| springConfig | Partial<AnimationConfig> |
TimePickerSeconds
| Prop name | Type | Default | Description |
|---|---|---|---|
| as | any | Tag or component, but a simple tag (i.e. built-in components, e.g. div, span) is recommended. | |
| header | ReactNode | Second | |
| headerProps | HeaderProps | ||
| index | number | ||
| scrollerProps | TimePickerScrollerProps & { ref?: Ref<HTMLDivElement>; } |