DatePicker
DatePicker
To select or input a date.
Importimport{ DatePicker }from"antd"; |
Sourcecomponents/date-picker |
- Components Overview
- General
- Layout
- Navigation
- Data Entry
- Data Display
- Feedback
- Other
Importimport{ DatePicker }from"antd"; |
Sourcecomponents/date-picker |
By clicking the input box, you can select a date from a popup calendar.
Common props ref：Common props
There are five kinds of picker:
The default locale is en-US, if you need to use other languages, recommend to use internationalized components provided by us at the entrance. Look at: ConfigProvider.
If there are special needs (only modifying single component language), Please use the property: local. Example: default.
// The default locale is en-US, if you want to use other locale, just set locale in entry file globally.// Make sure you import the relevant dayjs file as well, otherwise the locale won't change for all texts (e.g. range picker months)import locale from 'antd/locale/zh_CN';import dayjs from 'dayjs';import 'dayjs/locale/zh-cn';dayjs.locale('zh-cn');<ConfigProvider locale={locale}><DatePicker defaultValue={dayjs('2015-01-01', 'YYYY-MM-DD')} /></ConfigProvider>;
When use with Next.js App Router, make sure to add 'use client' before import locale file of dayjs. It's because all components of Ant Design only works in client, importing locale in RSC will not work.
The following APIs are shared by DatePicker, RangePicker.
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| allowClear | Customize clear button | boolean | { clearIcon?: ReactNode } | true | 5.8.0: Support object type |
| autoFocus | If get focus when component mounted | boolean | false | |
| className | The picker className | string | - | |
| dateRender | Custom rendering function for date cells, >= 5.4.0 use cellRender instead. | function(currentDate: dayjs, today: dayjs) => React.ReactNode | - | < 5.4.0 |
| cellRender | Custom rendering function for picker cells | (current: dayjs, info: { originNode: React.ReactElement,today: DateType, range?: 'start' | 'end', type: PanelMode, locale?: Locale, subType?: 'hour' | 'minute' | 'second' | 'meridiem' }) => React.ReactNode | - | 5.4.0 |
| components | Custom panels | Record<Panel | 'input', React.ComponentType> | - | 5.14.0 |
| disabled | Determine whether the DatePicker is disabled | boolean | false | |
| disabledDate | Specify the date that cannot be selected | (currentDate: dayjs, info: { from?: dayjs, type: Picker }) => boolean | - | info: 5.14.0 |
| format | To set the date format, support multi-format matching when it is an array, display the first one shall prevail. refer to dayjs#format. for example: Custom Format | formatType | rc-picker | |
| order | Auto order date when multiple or range selection | boolean | true | 5.14.0 |
| popupClassName | To customize the className of the popup calendar | string | - | 4.23.0 |
| preserveInvalidOnBlur | Not clean input on blur even when the typing is invalidate | boolean | false | 5.14.0 |
| getPopupContainer | To set the container of the floating layer, while the default is to create a div element in body | function(trigger) | - | |
| inputReadOnly | Set the readonly attribute of the input tag (avoids virtual keyboard on touch devices) | boolean | false | |
| locale | Localization configuration | object | default | |
| minDate | The minimum date, which also limits the range of panel switching | dayjs | - | 5.14.0 |
| maxDate | The maximum date, which also limits the range of panel switching | dayjs | - | 5.14.0 |
| mode | The picker panel mode（ Cannot select year or month anymore? ) | time | date | month | year | decade | - | |
| needConfirm | Need click confirm button to trigger value change. Default false when multiple | boolean | - | 5.14.0 |
| nextIcon | The custom next icon | ReactNode | - | 4.17.0 |
| open | The open state of picker | boolean | - | |
| panelRender | Customize panel render | (panelNode) => ReactNode | - | 4.5.0 |
| picker | Set picker type | date | week | month | quarter | year | date | quarter: 4.1.0 |
| placeholder | The placeholder of date input | string | [string,string] | - | |
| placement | The position where the selection box pops up | bottomLeft bottomRight topLeft topRight | bottomLeft | |
| popupStyle | To customize the style of the popup calendar | CSSProperties | {} | |
| prefix | The custom prefix | ReactNode | - | 5.22.0 |
| presets | The preset ranges for quick selection, Since 5.8.0, preset value supports callback function. | { label: React.ReactNode, value: Dayjs | (() => Dayjs) }[] | - | |
| prevIcon | The custom prev icon | ReactNode | - | 4.17.0 |
| size | To determine the size of the input box, the height of large and small, are 40px and 24px respectively, while default size is 32px | large | middle | small | - | |
| status | Set validation status | 'error' | 'warning' | - | 4.19.0 |
| style | To customize the style of the input box | CSSProperties | {} | |
| suffixIcon | The custom suffix icon | ReactNode | - | |
| superNextIcon | The custom super next icon | ReactNode | - | 4.17.0 |
| superPrevIcon | The custom super prev icon | ReactNode | - | 4.17.0 |
| variant | Variants of picker | outlined | borderless | filled | outlined | 5.13.0 |
| onOpenChange | Callback function, can be executed whether the popup calendar is popped up or closed | function(open) | - | |
| onPanelChange | Callback when picker panel mode is changed | function(value, mode) | - |
| Name | Description | Version |
|---|---|---|
| blur() | Remove focus | |
| focus() | Get focus |
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| defaultPickerValue | Default panel date, will be reset when panel open | dayjs | - | 5.14.0 |
| defaultValue | To set default date, if start time or end time is null or undefined, the date range will be an open interval | dayjs | - | |
| disabledTime | To specify the time that cannot be selected | function(date) | - | |
| format | To set the date format. refer to dayjs#format | formatType | YYYY-MM-DD | |
| multiple | Enable multiple selection. Not support showTime | boolean | false | 5.14.0 |
| pickerValue | Panel date. Used for controlled switching of panel date. Work with onPanelChange | dayjs | - | 5.14.0 |
| renderExtraFooter | Render extra footer in panel | (mode) => React.ReactNode | - | |
| showNow | Show the fast access of current datetime | boolean | - | 4.4.0 |
| showTime | To provide an additional time selection | object | boolean | TimePicker Options | |
| showTime.defaultValue | To set default time of selected date, demo | dayjs | dayjs() | |
| showWeek | Show week info when in DatePicker | boolean | false | 5.14.0 |
| value | To set date | dayjs | - | |
| onChange | Callback function, can be executed when the selected time is changing | function(date: dayjs, dateString: string) | - | |
| onOk | Callback when click ok button | function() | - | |
| onPanelChange | Callback function for panel changing | function(value, mode) | - |
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| defaultValue | To set default date | dayjs | - | |
| format | To set the date format. refer to dayjs#format | formatType | YYYY | |
| multiple | Enable multiple selection | boolean | false | 5.14.0 |
| renderExtraFooter | Render extra footer in panel | () => React.ReactNode | - | |
| value | To set date | dayjs | - | |
| onChange | Callback function, can be executed when the selected time is changing | function(date: dayjs, dateString: string) | - |
Added in 4.1.0.
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| defaultValue | To set default date | dayjs | - | |
| format | To set the date format. refer to dayjs#format | formatType | YYYY-\QQ | |
| multiple | Enable multiple selection | boolean | false | 5.14.0 |
| renderExtraFooter | Render extra footer in panel | () => React.ReactNode | - | |
| value | To set date | dayjs | - | |
| onChange | Callback function, can be executed when the selected time is changing | function(date: dayjs, dateString: string) | - |
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| defaultValue | To set default date | dayjs | - | |
| format | To set the date format. refer to dayjs#format | formatType | YYYY-MM | |
| multiple | Enable multiple selection | boolean | false | 5.14.0 |
| renderExtraFooter | Render extra footer in panel | () => React.ReactNode | - | |
| value | To set date | dayjs | - | |
| onChange | Callback function, can be executed when the selected time is changing | function(date: dayjs, dateString: string) | - |
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| defaultValue | To set default date | dayjs | - | |
| format | To set the date format. refer to dayjs#format | formatType | YYYY-wo | |
| multiple | Enable multiple selection | boolean | false | 5.14.0 |
| renderExtraFooter | Render extra footer in panel | (mode) => React.ReactNode | - | |
| value | To set date | dayjs | - | |
| onChange | Callback function, can be executed when the selected time is changing | function(date: dayjs, dateString: string) | - | |
| showWeek | Show week info when in DatePicker | boolean | true | 5.14.0 |
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| allowEmpty | Allow start or end input leave empty | [boolean, boolean] | [false, false] | |
| cellRender | Custom rendering function for picker cells | (current: dayjs, info: { originNode: React.ReactElement,today: DateType, range?: 'start' | 'end', type: PanelMode, locale?: Locale, subType?: 'hour' | 'minute' | 'second' | 'meridiem' }) => React.ReactNode | - | 5.4.0 |
| dateRender | Custom rendering function for date cells, >= 5.4.0 use cellRender instead. | function(currentDate: dayjs, today: dayjs) => React.ReactNode | - | < 5.4.0 |
| defaultPickerValue | Default panel date, will be reset when panel open | dayjs | - | 5.14.0 |
| defaultValue | To set default date | [dayjs, dayjs] | - | |
| disabled | If disable start or end | [boolean, boolean] | - | |
| disabledTime | To specify the time that cannot be selected | function(date: dayjs, partial: start | end, info: { from?: dayjs }) | - | info.from: 5.17.0 |
| format | To set the date format. refer to dayjs#format | formatType | YYYY-MM-DD HH:mm:ss | |
| id | Config input ids | { start?: string, end?: string } | - | 5.14.0 |
| pickerValue | Panel date. Used for controlled switching of panel date. Work with onPanelChange | dayjs | - | 5.14.0 |
| presets | The preset ranges for quick selection, Since 5.8.0, preset value supports callback function. | { label: React.ReactNode, value: (Dayjs | (() => Dayjs))[] }[] | - | |
| renderExtraFooter | Render extra footer in panel | () => React.ReactNode | - | |
| separator | Set separator between inputs | React.ReactNode | <SwapRightOutlined /> | |
| showTime | To provide an additional time selection | object | boolean | TimePicker Options | |
| showTime.defaultValue | To set default time of selected date, demo | dayjs[] | [dayjs(), dayjs()] | |
| value | To set date | [dayjs, dayjs] | - | |
| onCalendarChange | Callback function, can be executed when the start time or the end time of the range is changing. info argument is added in 4.4.0 | function(dates: [dayjs, dayjs], dateStrings: [string, string], info: { range:start|end }) | - | |
| onChange | Callback function, can be executed when the selected time is changing | function(dates: [dayjs, dayjs], dateStrings: [string, string]) | - | |
| onFocus | Trigger when get focus | function(event, { range: 'start' | 'end' }) | - | range: 5.14.0 |
| onBlur | Trigger when lose focus | function(event, { range: 'start' | 'end' }) | - | range: 5.14.0 |
import type { Dayjs } from 'dayjs';type Generic = string;type GenericFn = (value: Dayjs) => string;export type FormatType =| Generic| GenericFn| Array<Generic | GenericFn>| {format: string;type?: 'mask';};
Note: type is added in 5.14.0.
| Token Name | Description | Type | Default Value |
|---|---|---|---|
| activeBg | Background color when the input box is activated | string | #ffffff |
| activeBorderColor | Active border color | string | #1677ff |
| activeShadow | Box-shadow when active | string | 0 0 0 2px rgba(5, 145, 255, 0.1) |
| addonBg | Background color of addon | string | rgba(0, 0, 0, 0.02) |
| cellActiveWithRangeBg | Background color of cell in range | string | #e6f4ff |
| cellBgDisabled | Background color of disabled cell | string | rgba(0, 0, 0, 0.04) |
| cellHeight | Height of cell | number | 24 |
| cellHoverBg | Background color of cell hover state | string | rgba(0, 0, 0, 0.04) |
| cellHoverWithRangeBg | Background color of hovered cell in range | string | #c8dfff |
| cellRangeBorderColor | Border color of cell in range when picking | string | #7cb3ff |
| cellWidth | Width of cell | number | 36 |
| errorActiveShadow | Box-shadow when active in error status | string | 0 0 0 2px rgba(255, 38, 5, 0.06) |
| hoverBg | Background color when the input box hovers | string | #ffffff |
| hoverBorderColor | Hover border color | string | #4096ff |
| inputFontSize | Font size | number | 14 |
| inputFontSizeLG | Font size of large | number | 16 |
| inputFontSizeSM | Font size of small | number | 14 |
| multipleItemBg | Background color of multiple tag | string | rgba(0, 0, 0, 0.06) |
| multipleItemBorderColor | Border color of multiple tag | string | transparent |
| multipleItemBorderColorDisabled | Border color of multiple tag when disabled | string | transparent |
| multipleItemColorDisabled | Text color of multiple tag when disabled | string | rgba(0, 0, 0, 0.25) |
| multipleItemHeight | Height of multiple tag | number | 24 |
| multipleItemHeightLG | Height of multiple tag with large size | number | 32 |
| multipleItemHeightSM | Height of multiple tag with small size | number | 16 |
| multipleSelectorBgDisabled | Background color of multiple selector when disabled | string | rgba(0, 0, 0, 0.04) |
| paddingBlock | Vertical padding of input | number | 4 |
| paddingBlockLG | Vertical padding of large input | number | 7 |
| paddingBlockSM | Vertical padding of small input | number | 0 |
| paddingInline | Horizontal padding of input | number | 11 |
| paddingInlineLG | Horizontal padding of large input | number | 11 |
| paddingInlineSM | Horizontal padding of small input | number | 7 |
| presetsMaxWidth | Max width of preset area | number | 200 |
| presetsWidth | Width of preset area | number | 120 |
| textHeight | Height of cell text | number | 40 |
| timeCellHeight | Height of time cell | number | 28 |
| timeColumnHeight | Height of time column | number | 224 |
| timeColumnWidth | Width of time column | number | 56 |
| warningActiveShadow | Box-shadow when active in warning status | string | 0 0 0 2px rgba(255, 215, 5, 0.1) |
| withoutTimeCellHeight | Height of decade/year/quarter/month/week cell | number | 66 |
| zIndexPopup | z-index of popup | number | 1050 |
Please refer FAQ
After selecting the year, the system directly switches to the date panel instead of month panel. This design is intended to reduce the user's operational burden by allowing them to complete the year modification with just one click, without having to enter the month selection interface again. At the same time, it also avoids additional cognitive burden of remembering the month.
Please refer Use custom date library
DatePicker default set locale as en in v4. You can config DatePicker locale prop or ConfigProvider locale prop instead.
See FAQ Date-related-components-locale-is-not-working?
Please use correct language (#5605), or update dayjs locale config:
import dayjs from 'dayjs';import 'dayjs/locale/zh-cn';import updateLocale from 'dayjs/plugin/updateLocale';dayjs.extend(updateLocale);dayjs.updateLocale('zh-cn', {weekStart: 0,});
panelRender?When you change the layout of nodes by panelRender, React will unmount and re-mount it which reset the component state. You should keep the layout stable. Please ref #27263 for more info.
Please refer to the blog 'Why is it so hard to disable the date?', to learn how to use it.
Basic use case. Users can select or input a date in a panel.
Multiple selections. Does not support showTime and picker="time".
DatePicker will automatically determine whether to show a confirm button according to the picker property. You can also set the needConfirm property to determine whether to show a confirm button. When needConfirm is set, the user must click the confirm button to complete the selection. Otherwise, the selection will be submitted when the picker loses focus or selects a date.
We can set the date format by format. When format is an array, the input box can be entered in any of the valid formats of the array.
Align the date format. Switch the selection by arrow keys. Will try to align the date to the last valid date when blur.
A disabled state of the DatePicker. You can also set as array to disable one of input.
Allow empty for the RangePicker. It's useful when you need to keep the "to date".
We can set preset ranges to RangePicker to improve user experience. Since 5.8.0, preset value supports callback function.
The input box comes in three sizes: small, middle and large. The middle size will be used if size is omitted.
Replace panel with components.
Add status to DatePicker with status, which could be error or warning.
Filled Debug
Determine which panel to show with mode and onPanelChange.
Custom prefix and suffixIcon.
Component Token Debug.
Set range picker type by picker prop.
Non-responsive spacing test.
Switch in different types of pickers by Select.
This property provides an additional time selection. When showTime is an Object, its properties will be passed on to the built-in TimePicker.
Limit the range of available dates by using minDate and maxDate.
Disable specific dates and times by using disabledDate and disabledTime respectively, and disabledTime only works with showTime.
Using info.from of disabledDate to limit the dynamic date range selection.
Render extra footer in panel for customized requirements.
We can customize the rendering of the cells in the calendar by providing a cellRender function to DatePicker.
Use locale to support special calendar format.
There are three variants: outlined filled and borderless.
You can manually specify the position of the popup via placement.
When RangePicker does not satisfied your requirements, try to implement similar functionality with two DatePicker.
- Use the
disabledDateproperty to limit the start and end dates.- Improve user experience with
openandonOpenChange.
Debug usage. Do not use in your production.
