DatePicker

To select or input a date.

When To Use

By clicking the input box, you can select a date from a popup calendar.

Examples

Basic

Basic use case. Users can select or input a date in panel.

Switchable picker

Switch in different types of pickers by Select.

Choose Time

This property provide an additional time selection. When showTime is an Object, its properties will be passed on to built-in TimePicker.

Disabled Date & Time

Disabled part of dates and time by disabledDate and disabledTime respectively, and disabledTime only works with showTime.

Preset Ranges

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

Three Sizes

The input box comes in three sizes. middle will be used if size is omitted.

Status

Add status to DatePicker with status, which could be error or warning.

Placement

You can manually specify the position of the popup via placement.

Range Picker

Set range picker type by picker prop.

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.

Disabled

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

Select range dates in 7 days

Using changeOnBlur work with onCalendarChange and disabledDate to limit date selection.

Customized Cell Rendering

We can customize the rendering of the cells in the calendar by providing a cellRender function to DatePicker.

Bordered-less

Bordered-less style component.

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.

import 'dayjs/locale/zh-cn';
import locale from 'antd/es/date-picker/locale/zh_CN';

<DatePicker locale={locale} />;

// The default locale is en-US, if you want to use other locale, just set locale in entry file globally.
import dayjs from 'dayjs';
import 'dayjs/locale/zh-cn';
import locale from 'antd/locale/zh_CN';

<ConfigProvider locale={locale}>
  <DatePicker defaultValue={dayjs('2015-01-01', 'YYYY-MM-DD')} />
</ConfigProvider>;

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
bordered	Whether has border style	boolean	true
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
changeOnBlur	Trigger `change` when blur. e.g. datetime picker no need click confirm button	boolean	false	5.5.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
disabled	Determine whether the DatePicker is disabled	boolean	false
disabledDate	Specify the date that cannot be selected	(currentDate: dayjs) => boolean	-
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
popupClassName	To customize the className of the popup calendar	string	-	4.23.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
mode	The picker panel mode（ Cannot select year or month anymore? )	`time` \| `date` \| `month` \| `year` \| `decade`	-
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	{}
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
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	To set default picker date	dayjs	-
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`
renderExtraFooter	Render extra footer in panel	(mode) => React.ReactNode	-
showNow	Whether to show 'Now' button on panel when `showTime` is set	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()
showToday	Whether to show `Today` button	boolean	true
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
defaultPickerValue	To set default picker date	dayjs	-
defaultValue	To set default date	dayjs	-
format	To set the date format. refer to dayjs#format	formatType	`YYYY`
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
defaultPickerValue	To set default picker date	dayjs	-
defaultValue	To set default date	dayjs	-
format	To set the date format. refer to dayjs#format	formatType	`YYYY-\QQ`
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
defaultPickerValue	To set default picker date	dayjs	-
defaultValue	To set default date	dayjs	-
format	To set the date format. refer to dayjs#format	formatType	`YYYY-MM`
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
defaultPickerValue	To set default picker date	dayjs	-
defaultValue	To set default date	dayjs	-
format	To set the date format. refer to dayjs#format	formatType	`YYYY-wo`
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)	-

RangePicker

Property	Description	Type	Default	Version
allowEmpty	Allow start or end input leave empty	[boolean, boolean]	[false, false]
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
defaultPickerValue	To set default picker date	[dayjs, dayjs]	-
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`)	-
format	To set the date format. refer to dayjs#format	formatType	`YYYY-MM-DD HH:mm:ss`
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])	-

formatType

import type { Dayjs } from 'dayjs';

type Generic = string;
type GenericFn = (value: Dayjs) => string;

export type FormatType = Generic | GenericFn | Array<Generic | GenericFn>;

Design Token

Component Token

Global Token

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.

DatePickerChangelog

DatePickerChangelog

When To Use

Examples

API

Localization

Common API

Common Methods

DatePicker

DatePicker[picker=year]

DatePicker[picker=quarter]

DatePicker[picker=month]

DatePicker[picker=week]

RangePicker

formatType

Design Token

Component Token

Global 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?

When To Use

Examples

API

Localization

Common API

Common Methods

DatePicker

DatePicker[picker=year]

DatePicker[picker=quarter]

DatePicker[picker=month]

DatePicker[picker=week]

RangePicker

formatType

Design Token

Component Token

Global 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?

DatePicker

DatePicker

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

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