Input · DatePicker
The date selector is used to help the user select a compliant, formatted date (time) or date (time) range.


How to import

Basic Use

Picker Density

The density can be used to control the size of the picker panel. The compact is the small size and the default is the default size. Support after v1.17.0.

With an Embedded Label

Multiple Date Selection

Set Multiple to true, can choose multiple dates.

Date and Time Selection

Set type to dateTime, can choose date and time.
If you want to remove the infinite loop scrolling interaction of TimePicker, you can pass timePickerOpts into a specific configuration to close it.

Date Range Selection

Set type to dateRange, can choose the date range.
When you use range selection, if only one date is selected, onChange will not be triggered at this time. Only when both the start date and the end date are selected will onChange be triggered.

Date Time Range Selection

Set type to dateTimeRange, can choose the date range and choose time;

Input in Panel

Use insetInput to control whether the date panel is inset with the input box, the default is false. Supported since v2.7.0. Inset input boxes are suitable for the following scenarios:
  • Date and time selection, you can directly input the time through the embedded input box, no need to select the time through the scroll wheel
  • When triggerRender+ range selection, use the inset input box to modify the start and end dates independently
After insetInput is turned on, it includes the following functions:
  • After clicking the trigger, the panel will pop up in the original position by default. You can customize the popup position by position
  • Click the embedded date input box, the panel switches to date selection; click the embedded time input box, the panel switches to time selection
  • Consistent with the external input box, if an illegal date is entered, the date will return to the previous legal date after the panel is closed
Note that some adjustments and restrictions will be made to the components after opening insetInput:
1. Trigger style: the trigger is read-only when the panel is not open, and the trigger is disabled when it is open
2. Panel style: when type includes time, hide the toggle button at the bottom
3. After insetInput is enabled, the `format` API only supports the `dateFormat[ timeFormat]` format. Using other formats will affect the display of the inset input box placeholder and trigger text

Synchronously switch months

version:>= 1.28.0
In the scenario of range selection, turning on syncSwitchMonth means to switch the two panels simultaneously. The default is false.
Note: Clicking the year button will also switch the two panels synchronously. Switching the year and month from the scroll wheel will not switch the panels synchronously. This ensures the user's ability to select months at non-fixed intervals.

Panel Change Callback

onPanelChange will be called when the month or year of the panel is changed.

Select Week

daterange is used with startDateOffset and endDateOffset to select range with single click, such as weekly selection and biweekly selection. Support after v1.10.0.


Version: > = 0.21.0
Set type to month, can make year-to-month selection.

Year and Month Range Selection

version: >= 2.32.0
Set type to monthRange to select the year and month range, small size and quick panel are not supported yet.

Confirm Date and Time Selection

Version: > = 0.18.0
For the selection of "datetime" (type = "dateTime") or "datetime range" (type = "dateTimeRange"), you can confirm it before writing the value into the input box. You can pass NeedConfirm = true to enable this behavior.
At the same time, the click callbacks of the "onConfirm" and "onCancel" buttons are supported.
The following example binds three callbacks: onChange, onConfirm and onCancel, and you can open the console to see the difference in print information.
Note: When opening needConfirm, you need to click the cancel button to close the panel, and clicking the blank area will no longer close the panel (v2.2.0)

Date and Time Selection with Shortcuts

Pass parameter Presets to set shortcuts for date selection.

Render TopSlot/BottomSlot

With topSlot and bottomSlot, you can customize the rendering of the top and bottom extra areas.

Disable Date Selection

Disable Partial Date or Time

Pass in disabledDate to disable the specified date, pass in disabledTime to disable the specified time, and with defaultPickerValue you can specify the year and month when the panel is opened.
disabledDate anddisabledTime, the accepted input parameters are the current date, the former returns a boolean value, the latter returns an object It will be directly passed to the TimePicker component.
When you use timeZone, the Date of the first parameter is the time under the time zone you choose (similar to the first return value of onChange)
When type contains range, the date can be disabled dynamically according to the rangeStart. The options parameter is supported after 1.9.0
When type contains range, dates can be disabled based on the focus state. The focus state is passed through the rangeInputFocus parameter in options.

Custom Display Format

Pass parameter format to custom display format.

Custom Trigger

Version: >=0.34.0
By default we use the Input component as the trigger for the DatePicker component. You can customize this trigger by passing the triggerRender method.
The custom trigger is a complete customization of the trigger, the default clear button will not take effect, if you need clear function, please customize a clear button.
When DatePicker is range type, the default date selected after the panel is opened is the start date, and it will switch to the end date selection after selection. The focus is reset when the panel is closed.
We recommend providing a clear button, when you pass null value to DatePicker, DatePicker will also reset focus internally. This allows the user to reselect the date range after clearing. (from v2.15)

Custom Render Date Content

renderDate: (dayNumber: number, fullDate: string) => ReactNode
  • dayNumber: such as 13.
  • fullDate: such as 2020-08-13.

Custom Render Date Box

renderFullDate: (dayNumber: number, fullDate: string, dayStatus: object) => ReactNode
dayStatus is this status of current date box. The included keys are as follows.

API Reference

autoAdjustOverflowWhether the floating layer automatically adjusts its direction when it is blockedbooleantrue0.34.0
autoFocusAutomatic access to focusbooleanfalse1.10.0
autoSwitchDateWhen the year and month are changed through the left and right buttons and the drop-down menu at the top of the panel, the date is automatically switched. Only valid for date type.booleantrue1.13.0
bottomSlotRender the bottom extra areaReactNode1.22.0
borderlessborderless mode >=2.33.0boolean
classNameClass namestring-
clearIconCan be used to customize the clear button, valid when showClear is trueReactNode2.25.0
defaultOpenPanel displays or hides by defaultbooleanfalse
defaultPickerValueDefault panel dateValueType
defaultValueDefault valueValueType
densityDensity of picker panel, one of default, compactstringdefault1.17.0
disabledIs it disabled?booleanfalse
disabledDateThe date is prohibited from the judgment method, and the date is prohibited when returned to true. Options parameter supported after 1.9.0, rangeEnd supported after 1.29 and rangeInputFocus is supported since 2.22
(date, options) => boolean
() = > false
disabledTimeTime prohibition configuration, the return value will be transparently passed to TimePicker as a parameter
(date, panelType) => object
() => false0.36.0
disabledTimePickerDisable time selection or not.boolean0.32.0
dropdownClassNameCSS classname for drop-down menustring1.13.0
dropdownMarginPopup 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, same as Tooltip marginobject|number2.25.0
dropdownStyleInline style of drop-down menuobject1.13.0
endDateOffsetWhen type is dateRange, set the end date of the selected range(selectedDate?: Date) => Date;-1.10.0
formatDate string format displayed in the input boxstringCorresponding to type: For details, see Date and Time Format
getPopupContainerSpecifies the parent DOM, and the bullet layer will be rendered to the DOM, you need to set 'position: relative` This will change the DOM tree position, but not the view's rendering position.function():HTMLElement() = > document.body
inputReadOnlyIs the text box readonlybooleanfalse
insetInputWhether the input box is embedded in the panel. InsetInputProps type supported after v2.29boolean |
inputStyleInput box styleobject
insetLabelPrefix label, lower priority than prefixstring|ReactNode
maxWhen multiple is set to true, the number of selected, non-pass or value is null|undefined, unlimited.number-
multipleWhether you can choose multiple, only type = "date" is supportedbooleanfalse
needConfirmDo you need to "confirm selection", only type= "dateTime"\| "dateTimeRange" works.boolean0.18.0
openControlled properties displayed or hidden by panelsboolean
placeholderInput box prompts textstring|string[]'Select date'
positionFloating layer position, optional value with Popover #API Reference · positionstring'bottomLeft'
prefixPrefix contentstring|ReactNode
presetsDate Time Shortcut, start and end support function type after v2.52
preventScrollIndicates 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 userboolean
presetPositionDate time shortcut panel position, optional 'left', 'right', 'top', 'bottom''bottom'2.18.0
rangeSeparatorCustom range type picker separator of input triggerstring'~'1.31.0
renderDateCustom date display content(dayNumber, fullDate) => ReactNode-1.4.0
renderFullDateCustom display date box(dayNumber, fullDate, dayStatus) => ReactNode-1.4.0
showClearDo you show the clear button?booleantrue0.35.0
sizeSize, optional: "small," "default," "large"string'default'
spacingThe distance between the pop-up layer and the children elementnumber41.9.0
startDateOffsetWhen type is dateRange, set the start date of the selected range(selectedDate?: Date) => Date;-1.10.0
startYearstart year of the year scroll panelnumber100 years before current year2.36.0
endYearend year of the year scroll panelnumber100 years after current year2.36.0
stopPropagationWhether to prevent click events on the popup layer from bubblingbooleantrue
syncSwitchMonthIn the scene of range, it supports synchronous switching of the month of the dual panelbooleanfalse1.28.0
timePickerOptsFor other parameters that can be transparently passed to the time selector, see TimePicker·API Referenceobject1.1.0
topSlotRender the top extra areaReactNode1.22.0
triggerRenderCustom trigger rendering method(TriggerRenderProps) => ReactNode0.34.0
typeType, optional value: "date", "dateRange", "dateTime", "dateTimeRange", "month", "monthRange"string'date'
valueControlled valueValueType
weekStartsOnTake the day of the week as the first day of the week, 0 for Sunday, 1 for Monday, and so on.number0
onBlurCallback when focus is lost. It is not recommended to use this API in range selection(event) => void() => {}1.0.0
onCancelCancel the callback when selected, enter the reference as the value of the last confirmed selection, only type equals "dateTime"or "dateTimeRange" and needConfirm equals true
(date, dateString) => void
onChangeA callback when the value changes
(date, dateString) => void
onClearA callback when click the clear button(event) => void() => {}1.16.0
onClickOutSideWhen the pop-up layer is in a display state, click the non-popup layer and trigger callback() => void() => {}2.31.0
onConfirmConfirm the callback at the time of selection, enter the reference as the value of the current selection, only type equals "dateTime" or "dateTimeRange" and needConfirm equals true
(date, dateString) => void
onFocusCallback when focus is obtained. It is not recommended to use this API in range selection(event) => void() => {}1.0.0
onOpenChangeCallback when popup open or close(isOpen) => void
onPanelChangeCallback when the year or date of the panel is switched
(date, dateStr) => void
onPresetClickCallback when click preset button
(item, e) => void
yearAndMonthOptsOther parameters that can be transparently passed to the year-month selector, see details in ScrollList#APIobject2.22.0


openThe dropdown can be manually opened when calling2.31.0
closeThe dropdown can be manually closed when calling2.31.0
focusThe input box can be manually focused when called2.31.0
blurThe input box can be manually blurred when called2.31.0

Interface Define



  • When a date is not selected, the aria-label of the trigger is Choose date, and when a date is selected, the aria-label of the trigger is Change date
  • The role of the month in the date panel is grid, the role of the week is set to row, and the date cell is set to gridcell
  • aria-disabled is true for the corresponding option when date and time are disabled
  • When multi-selected, aria-multiselectable of month is true, and aria-selected of date grid is true when selected
  • Some decorative icons in the panel, their aria-hidden is true

Date and Time Format

Adopted in the semi-ui component library date-fns(v2.9.0) As a date and time engine, formatting token means the following:
  • "y": Year
  • "M": month
  • "d": day
  • "H": hours
  • "h": hours (12h)
  • "m": minutes
  • "s": seconds
The following uses new Date('2023-12-09 08:08:00') or [new Date('2023-12-09 08:08:00'), new Date('2023-12-10 10 :08:00')] as value to explain the impact of different types and different format values on the displayed value:
typeformatdisplay value
dateTimeyyyy-MM-dd HH:mm:ss2023-12-09 08:08:00
dateRangeyyyy-MM-dd2023-12-09 ~ 2023-12-10
dateTimeRangeyyyy-MM-dd HH:mm:ss2023-12-09 08:08 ~ 2023-12-10 10:08
Multiple dates or times are used by default "," (English comma) separated.
More token available Date-fns official website

Content Guidelines

  • Date picker is recommended to be used with tags
  • Use concise labels to indicate what the date selection refers to
  • Please refer to Date and Time

Design Tokens


  • Date time picker, when you choose time, minute and second, you don't want to scroll infinitely. How to achieve the effect?
    This behavior can be controlled by a specific switch in timePickerOpts, timePickerOpts={{scrollItemProps: {cycled: false}}}, and cycled is set to false
  • How to set the default display time when the panel is opened?
    You can use the defaultPickerValue property.
  • Date time selection, range date selection, after inputting some dates, the panel does not echo the date?
    The input box needs to be entered completely before it is showed to the panel. For example, for dateTime type, the full requested date and time have been entered. For dateRange type, full requires start and end dates to be entered.
  • What is the displayed time at the bottom of the date time selection panel?
    When no time is selected, it is the value of the time in defaultPickerValue, if not set it is the time when the panel was opened. After selecting a time, it is the selected time.
    Since it has two hidden meanings in design, which may lead to ambiguity, it is recommended to use inline styles and open them through insetInput. It is recommended to read the relevant Documentation before use.