---
localeCode: en-US
order: 50
category: Input
title: TimePicker
subTitle: TimePicker
icon: doc-timepicker
brief: Users can easily select a compliant, formatted point of time using the time selector.
---
## Demos
### How to import
```jsx import
import { TimePicker } from '@douyinfe/semi-ui';
```
### Basic Usage
Click TimePicker, and then you can select or enter a time in the floating layer.
```jsx live=true
import React from 'react';
import { TimePicker } from '@douyinfe/semi-ui';
function Demo() {
return ;
}
```
### Infinite Scroll
Starting from version V2.22.0, we changed the default mode of ScrollItem in TimePicker from `wheel` to `normal`. If you want to apply the effect of infinite scrolling back, please refer to the following example.
```jsx live=true
import React from 'react';
import { TimePicker } from '@douyinfe/semi-ui';
function Demo() {
return ;
}
```
### Controlled Component
When using `value` And not. `defaultValue` When used as a controlled component.`value` and `onChange` It needs to be used in conjunction.
```jsx live=true
import React, { useState } from 'react';
import { TimePicker } from '@douyinfe/semi-ui';
() => {
const [value, setValue] = useState(null);
const onChange = (time) => {
console.log(time);
setValue(time);
};
return ;
};
```
### Different Format
The columns in the TimePicker float will follow `format` Change, when omitted `format` At some point, the corresponding column in the floating layer will also disappear.
NOTE: `format` Follow the date-fns `format` Format. https://date-fns.org/v2.0.0/docs/format
```jsx live=true
import React from 'react';
import { TimePicker } from '@douyinfe/semi-ui';
function Demo() {
return ;
}
```
### Set Panel Header and Footer
```jsx live=true
import React, { useState } from 'react';
import { TimePicker, Button } from '@douyinfe/semi-ui';
function Demo() {
const [open, setOpen] = useState(false);
const closePanel = () => setOpen(false);
const onOpenChange = open => {
setOpen(open);
console.log(open);
};
return (
);
}
```
### Disable Time Selection
```jsx live=true
import React from 'react';
import { TimePicker } from '@douyinfe/semi-ui';
function Demo() {
return ;
}
```
### Set Step Length
Available `Hour Step`, `Minute Step`, `Second Step` Show the optional minutes and seconds by step.
```jsx live=true
import React from 'react';
import { TimePicker } from '@douyinfe/semi-ui';
function Demo() {
return ;
}
```
### 12-hour System
12-hour time selector, default `format` for `h:mm:ss a`, an incoming `format` The format must be in [dateFns date format](https://date-fns.org/v2.0.0/docs/format)Within range.
> For example, the default 12-hour format string is:`a h:mm:ss`, if passed in `A h:mm:ss` This will result in an inability to format correctly.
```jsx live=true
import React from 'react';
import { TimePicker } from '@douyinfe/semi-ui';
function Demo() {
return (
);
}
```
### Time Range
Pass type = "timeRange" to enable time range selection.
```jsx live=true
import React from 'react';
import { TimePicker } from '@douyinfe/semi-ui';
function Demo() {
return (
);
}
```
### Disable left/right panels in Range mode (disabledTime)
When `type="timeRange"`, you can use `disabledTime(value, panelType)` to apply different disabled rules for the left/right panel.
- `value`: `Date` in single mode; `Date[]` in range mode (might be empty / length 1 / length 2)
- `panelType`: `'left' | 'right'`, representing start/end panel
In the following demo, after selecting a start time, the right (end) panel will disable options earlier than the start time.
```jsx live=true hideInDSM
import React from 'react';
import { TimePicker } from '@douyinfe/semi-ui';
function Demo() {
return (
{
const start = Array.isArray(value) ? value[0] : value;
if (panelType === 'right' && start instanceof Date) {
const h = start.getHours();
const m = start.getMinutes();
return {
disabledHours: () => Array.from({ length: h }, (_, i) => i),
disabledMinutes: hour => (hour === h ? Array.from({ length: m }, (_, i) => i) : []),
};
}
return {};
}}
/>
);
}
```
### Custom Trigger
By default we use the `Input` component as the trigger for the `DatePicker` component. You can customize this trigger by passing the `triggerRender` method.
```jsx live=true hideInDSM
import React, { useState, useMemo } from 'react';
import * as dateFns from 'date-fns';
import { TimePicker, Button } from '@douyinfe/semi-ui';
import { IconChevronDown, IconClose } from '@douyinfe/semi-icons';
function Demo() {
const formatToken = 'HH:mm:ss';
const [time, setTime] = useState(new Date());
return (
setTime(time)}
triggerRender={({ placeholder }) => (
}
>
{time ? dateFns.format(time, formatToken) : placeholder}
)}
/>
);
}
```
## TimeZone Config
Semi All configuration about time zone is converged in [ConfigProvider](/en-US/other/configprovider)
```jsx live=true hideInDSM
import React, { useMemo, useState } from 'react';
import { ConfigProvider, Select, TimePicker } from '@douyinfe/semi-ui';
function Demo(props = {}) {
const [timeZone, setTimeZone] = useState('GMT+08:00');
const defaultTimestamp = 1581599305265;
const gmtList = useMemo(() => {
const list = [];
for (let hourOffset = -11; hourOffset <= 14; hourOffset++) {
const prefix = hourOffset >= 0 ? '+' : '-';
const hOffset = Math.abs(parseInt(hourOffset, 10));
list.push(`GMT${prefix}${String(hOffset).padStart(2, '0')}:00`);
}
return list;
}, []);
return (
);
}
```
## API Reference
| Parameters | Instructions | Type | Default | Version |
| --- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| --- | --- | --- |
| autoAdjustOverflow | Whether the floating layer automatically adjusts its direction when it is blocked | boolean | true | |
| autoFocus | Automatic access to focus | boolean | false |
| borderless | borderless mode >=2.33.0 | boolean | |
| className | Outer style name | string | |
| clearIcon | Can be used to customize the clear button, valid when showClear is true | ReactNode | | **2.25.0**|
| clearText | Clear button prompt copy | string | Clear |
| defaultOpen | Whether the panel is open by default | boolean | | |
| defaultValue | Default time | Date\|timeStamp\|string (array when type = "timeRange") | |
| disabled | Disable all operations | boolean | false |
| disabledHours | Prohibited selection of partial hour options | () => number [] | |
| disabledMinutes | Prohibited to select some minute options | (selectedHour: number) => number[] | |
| disabledSeconds | Unable to select partial second option | (selectedHour: number, selectedMinute: number) => number[] | |
| disabledTime | **Range mode only**: derive disabled configuration based on currently selected dates and panel position, allowing left and right panels to use different rules. Params — `value`: currently selected dates (array length 0/1/2); `panelType`: `'left'` or `'right'`. Fields returned by the callback **override** the corresponding top-level `disabledHours` / `disabledMinutes` / `disabledSeconds`; fields that are not returned **fall back** to the top-level props (return a function returning `[]` if you want to clear the top-level rule for that panel). In single mode this prop is ignored — use the top-level `disabledHours` / `disabledMinutes` / `disabledSeconds` instead. | (value: Date[], panelType: 'left' \| 'right') => { disabledHours?: () => number[]; disabledMinutes?: (selectedHour: number) => number[]; disabledSeconds?: (selectedHour: number, selectedMinute: number) => number[] } | | **2.97.0** |
| dropdownMargin | Popup layer calculates the size of the safe area when the current direction overflows, used in scenes covered by fixed elements, more detail refer to [issue#549](https://github.com/DouyinFE/semi-design/issues/549), same as Tooltip margin | object\|number | | **2.25.0** |
| focusOnOpen | Whether to open the panel and focus the input box when mounting | boolean | false | |
| format | Time format of presentation | string | "HH: mm: ss." | |
| getPopupContainer | Specifies the container and the floating layer will be rendered into the element, you need to set 'position: relative` This will change the DOM tree position, but not the view's rendering position. | () => HTMLElement | () => document.body |
| hideDisabledOptions | Hide the option of forbidden selection | boolean | false |
| hourStep | Hour option interval | number | 1 |
| inputReadOnly | Set the input box to read-only (avoid opening a virtual keyboard on a mobile device) | boolean | false |
| minuteStep | Minute option interval | number | 1 |
| motion | Whether to display the pop-up layer animation | boolean | true | |
| open | Controlled property of whether the panel is open | boolean | |
| panelFooter | Addon at the bottom of the panel | ReactNode\|ReactNode[]\|string | |
| panelHeader | Panel head addon | ReactNode\|ReactNode[]\|string | |
| placeholder | What's displayed when it's not worth it. | string | "Select time" |
| popupClassName | Pop-up class name | string | '' |
| popupStyle | Pop-up layer style object | object | - |
| position | Floating position | string | type="timeRange" => "bottom" type="time" => "bottomLeft" |
| prefix | Prefix content | string\|ReactNode | | |
| preventScroll | Indicates whether the browser should scroll the document to display the newly focused element, acting on the focus method inside the component, excluding the component passed in by the user | boolean | | |
| rangeSeparator | time range delimiter | string | "~" |
| scrollItemProps | The props passed through to ScrollItem. The optional values are the same as [ScrollList#API](/zh-CN/show/scrolllist#ScrollItem) | object | | |
| secondStep | Second option interval | number | 1 |
| showClear | Whether to show the clear button | boolean | true | |
| stopPropagation | Whether to prevent click events on the popup layer from bubbling | boolean | true | **2.49.0** |
| size | Size of input box, one of 'default', 'small' and 'large' | string | 'default' | |
| triggerRender | Custom trigger rendering method | ({ placeholder: string }) => ReactNode | | |
| type | type | "time"\|"timeRange" | "time" |
| use12Hours | Using a 12-hour system, `format` default to `h: mm: ssa` when true | boolean | false |
| value | Current time | Date\|timeStamp\|string (array when type = "timeRange") | |
| onBlur | Callback when focus is lost | (e: domEvent) => void | () => {} | |
| onChange | A callback in time. | (time: Date\|Date[], timeString: string\|string[]) => void | |
| onChangeWithDateFirst | Set the order of parameter in `onChange`, `true`: (Date, string); `false`: (string, Date) | boolean | true | **2.4.0** |
| onFocus | Callback when focus is obtained | (e: domEvent) => void | () => {} | |
| onOpenChange | A callback when the panel is on / off | (isOpen: boolean) => void | |
## Methods
Some internal methods provided by TimePicker can be accessed through ref:
| Name | Description |
| ------- | ------------- |
| blur() | Remove focus |
| focus() | Get the focus |
## Content Guidelines
- The time selector includes at least hours and minutes, such as: 11:30, which can be adapted to 12-hour or 24-hour format during localization
- When 12-hour clock is selected, it needs to be used together with AM/PM
## Design Tokens