DatePicker

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.

5.14.0

Date Format

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.

Mask Format

Align the date format. Switch the selection by arrow keys. Will try to align the date to the last valid date when blur.

5.14.0

Disabled

A disabled state of the DatePicker. You can also set as array to disable one of input.

Allow Empty

Allow empty for the RangePicker. It's useful when you need to keep the "to date".

Preset Ranges

We can set preset ranges to RangePicker to improve user experience. Since 5.8.0, preset value supports callback function.

LargemiddleSmall

Three Sizes

The input box comes in three sizes: small, middle and large. The middle size will be used if size is omitted.

Customize Panel

Replace panel with components.

5.14.0

By locale props

By ConfigProvider

Buddhist Era

Use locale to support special calendar format.

5.14.0

Variants

Variants of DatePicker, there are four variants: outlined filled borderless and underlined.

5.13.0

Event Period

Prefix and Suffix

Custom prefix and suffixIcon.

API

Common props ref：Common props

There are five kinds of picker:

DatePicker
DatePicker[picker="month"]
DatePicker[picker="week"]
DatePicker[picker="year"]
DatePicker[picker="quarter"] (Added in 4.1.0)
RangePicker

Localization

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.

jsx

// 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>;

WARNING

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.

Common API

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
defaultOpen	Initial open state of picker	boolean	-
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, use `classNames.popup.root` instead	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, use `styles.popup.root` instead	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` \| `underlined`	`outlined`	5.13.0 \| `underlined`: 5.24.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)	-

Common Methods

Name	Description	Version
blur()	Remove focus
focus()	Get focus

DatePicker

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)	-

DatePicker[picker=year]

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)	-

DatePicker[picker=quarter]

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)	-

DatePicker[picker=month]

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)	-

DatePicker[picker=week]

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

RangePicker

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

formatType

typescript

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.

Semantic DOM

Single

Multiple

root
5.25.0
Root element
popup.root
5.25.0
Popup root element

Design Token

Component TokenHow to use?

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	#cbe0fd
cellRangeBorderColor	Border color of cell in range when picking	string	#82b4f9
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

Global TokenHow to use?

FAQ

When set mode to DatePicker/RangePicker, cannot select year or month anymore?

Please refer FAQ

Why does the date picker switch to the date panel after selecting the year instead of the month panel?

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.

How to use DatePicker with customize date library like dayjs?

Please refer Use custom date library

Why config dayjs.locale globally not work?

DatePicker default set locale as en in v4. You can config DatePicker locale prop or ConfigProvider locale prop instead.

How to modify start day of week?

Please use correct language (#5605), or update dayjs locale config:

Example: https://codesandbox.io/s/dayjs-day-of-week-x9tuj2?file=/demo.tsx

import dayjs from 'dayjs';

import 'dayjs/locale/zh-cn';

import updateLocale from 'dayjs/plugin/updateLocale';

dayjs.extend(updateLocale);
dayjs.updateLocale('zh-cn', {
  weekStart: 0,
});

Why origin panel don't switch when using `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.

How to understand disabled time and date?

Please refer to the blog 'Why is it so hard to disable the date?', to learn how to use it.

contributors

DatePicker

When To Use

Examples

7 days range

6 months range

By locale props

By ConfigProvider

API

Localization

Common API

Common Methods

DatePicker

DatePicker[picker=year]

DatePicker[picker=quarter]

DatePicker[picker=month]

DatePicker[picker=week]

RangePicker

formatType

Semantic DOM

root

popup.root

Design Token

FAQ

When set mode to DatePicker/RangePicker, cannot select year or month anymore?

Why does the date picker switch to the date panel after selecting the year instead of the month panel?

How to use DatePicker with customize date library like dayjs?

Why config dayjs.locale globally not work?

Date-related components locale is not working?

How to modify start day of week?

Why origin panel don't switch when using panelRender?

How to understand disabled time and date?

Why origin panel don't switch when using `panelRender`?