logoAnt Design

⌘ K
  • Design
  • Development
  • Components
  • Blog
  • Resources
5.25.0
  • Components Overview
  • General
    • Button
    • FloatButton
      5.0.0
    • Icon
    • Typography
  • Layout
    • Divider
    • Flex
      5.10.0
    • Grid
    • Layout
    • Space
    • Splitter
      5.21.0
  • Navigation
    • Anchor
    • Breadcrumb
    • Dropdown
    • Menu
    • Pagination
    • Steps
    • Tabs
  • Data Entry
    • AutoComplete
    • Cascader
    • Checkbox
    • ColorPicker
      5.5.0
    • DatePicker
    • Form
    • Input
    • InputNumber
    • Mentions
    • Radio
    • Rate
    • Select
    • Slider
    • Switch
    • TimePicker
    • Transfer
    • TreeSelect
    • Upload
  • Data Display
    • Avatar
    • Badge
    • Calendar
    • Card
    • Carousel
    • Collapse
    • Descriptions
    • Empty
    • Image
    • List
    • Popover
    • QRCode
      5.1.0
    • Segmented
    • Statistic
    • Table
    • Tag
    • Timeline
    • Tooltip
    • Tour
      5.0.0
    • Tree
  • Feedback
    • Alert
    • Drawer
    • Message
    • Modal
    • Notification
    • Popconfirm
    • Progress
    • Result
    • Skeleton
    • Spin
    • Watermark
      5.1.0
  • Other
    • Affix
    • App
      5.1.0
    • ConfigProvider
    • Util
      5.13.0

DatePicker

To select or input a date.
Importimport { DatePicker } from "antd";
Sourcecomponents/date-picker
Docs
Edit this pageChangelog

Resources

Ant Design X
Ant Design Charts
Ant Design Pro
Pro Components
Ant Design Mobile
Ant Design Mini
Ant Design Web3
Ant Design Landing-Landing Templates
Scaffolds-Scaffold Market
Umi-React Application Framework
dumi-Component doc generator
qiankun-Micro-Frontends Framework
Ant Motion-Motion Solution
China Mirror 🇨🇳

Community

Awesome Ant Design
Medium
Twitter
yuque logoAnt Design in YuQue
Ant Design in Zhihu
Experience Cloud Blog
seeconf logoSEE Conf-Experience Tech Conference

Help

GitHub
Change Log
FAQ
Bug Report
Issues
Discussions
StackOverflow
SegmentFault

Ant XTech logoMore Products

yuque logoYuQue-Document Collaboration Platform
AntV logoAntV-Data Visualization
Egg logoEgg-Enterprise Node.js Framework
Kitchen logoKitchen-Sketch Toolkit
Galacean logoGalacean-Interactive Graphics Solution
xtech logoAnt Financial Experience Tech
Theme Editor
Made with ❤ by
Ant Group and Ant Design Community
loading

When To Use

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

Examples

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.

PropertyDescriptionTypeDefaultVersion
allowClearCustomize clear buttonboolean | { clearIcon?: ReactNode }true5.8.0: Support object type
autoFocusIf get focus when component mountedbooleanfalse
classNameThe picker classNamestring-
dateRenderCustom rendering function for date cells, >= 5.4.0 use cellRender instead.function(currentDate: dayjs, today: dayjs) => React.ReactNode-< 5.4.0
cellRenderCustom 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
componentsCustom panelsRecord<Panel | 'input', React.ComponentType>-5.14.0
defaultOpenInitial open state of pickerboolean-
disabledDetermine whether the DatePicker is disabledbooleanfalse
disabledDateSpecify the date that cannot be selected(currentDate: dayjs, info: { from?: dayjs, type: Picker }) => boolean-info: 5.14.0
formatTo 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 FormatformatTyperc-picker
orderAuto order date when multiple or range selectionbooleantrue5.14.0
popupClassNameTo customize the className of the popup calendar, use classNames.popup.root insteadstring-4.23.0
preserveInvalidOnBlurNot clean input on blur even when the typing is invalidatebooleanfalse5.14.0
getPopupContainerTo set the container of the floating layer, while the default is to create a div element in bodyfunction(trigger)-
inputReadOnlySet the readonly attribute of the input tag (avoids virtual keyboard on touch devices)booleanfalse
localeLocalization configurationobjectdefault
minDateThe minimum date, which also limits the range of panel switchingdayjs-5.14.0
maxDateThe maximum date, which also limits the range of panel switchingdayjs-5.14.0
modeThe picker panel mode( Cannot select year or month anymore? )time | date | month | year | decade-
needConfirmNeed click confirm button to trigger value change. Default false when multipleboolean-5.14.0
nextIconThe custom next iconReactNode-4.17.0
openThe open state of pickerboolean-
panelRenderCustomize panel render(panelNode) => ReactNode-4.5.0
pickerSet picker typedate | week | month | quarter | yeardatequarter: 4.1.0
placeholderThe placeholder of date inputstring | [string,string]-
placementThe position where the selection box pops upbottomLeft bottomRight topLeft topRightbottomLeft
popupStyleTo customize the style of the popup calendar, use styles.popup.root insteadCSSProperties{}
prefixThe custom prefixReactNode-5.22.0
presetsThe preset ranges for quick selection, Since 5.8.0, preset value supports callback function.{ label: React.ReactNode, value: Dayjs | (() => Dayjs) }[]-
prevIconThe custom prev iconReactNode-4.17.0
sizeTo determine the size of the input box, the height of large and small, are 40px and 24px respectively, while default size is 32pxlarge | middle | small-
statusSet validation status'error' | 'warning'-4.19.0
styleTo customize the style of the input boxCSSProperties{}
suffixIconThe custom suffix iconReactNode-
superNextIconThe custom super next iconReactNode-4.17.0
superPrevIconThe custom super prev iconReactNode-4.17.0
variantVariants of pickeroutlined | borderless | filled | underlinedoutlined5.13.0 | underlined: 5.24.0
onOpenChangeCallback function, can be executed whether the popup calendar is popped up or closedfunction(open)-
onPanelChangeCallback when picker panel mode is changedfunction(value, mode)-

Common Methods

NameDescriptionVersion
blur()Remove focus
focus()Get focus

DatePicker

PropertyDescriptionTypeDefaultVersion
defaultPickerValueDefault panel date, will be reset when panel opendayjs-5.14.0
defaultValueTo set default date, if start time or end time is null or undefined, the date range will be an open intervaldayjs-
disabledTimeTo specify the time that cannot be selectedfunction(date)-
formatTo set the date format. refer to dayjs#formatformatTypeYYYY-MM-DD
multipleEnable multiple selection. Not support showTimebooleanfalse5.14.0
pickerValuePanel date. Used for controlled switching of panel date. Work with onPanelChangedayjs-5.14.0
renderExtraFooterRender extra footer in panel(mode) => React.ReactNode-
showNowShow the fast access of current datetimeboolean-4.4.0
showTimeTo provide an additional time selectionobject | booleanTimePicker Options
showTime.defaultValueTo set default time of selected date, demodayjsdayjs()
showWeekShow week info when in DatePickerbooleanfalse5.14.0
valueTo set datedayjs-
onChangeCallback function, can be executed when the selected time is changingfunction(date: dayjs, dateString: string)-
onOkCallback when click ok buttonfunction()-
onPanelChangeCallback function for panel changingfunction(value, mode)-

DatePicker[picker=year]

PropertyDescriptionTypeDefaultVersion
defaultValueTo set default datedayjs-
formatTo set the date format. refer to dayjs#formatformatTypeYYYY
multipleEnable multiple selectionbooleanfalse5.14.0
renderExtraFooterRender extra footer in panel() => React.ReactNode-
valueTo set datedayjs-
onChangeCallback function, can be executed when the selected time is changingfunction(date: dayjs, dateString: string)-

DatePicker[picker=quarter]

Added in 4.1.0.

PropertyDescriptionTypeDefaultVersion
defaultValueTo set default datedayjs-
formatTo set the date format. refer to dayjs#formatformatTypeYYYY-\QQ
multipleEnable multiple selectionbooleanfalse5.14.0
renderExtraFooterRender extra footer in panel() => React.ReactNode-
valueTo set datedayjs-
onChangeCallback function, can be executed when the selected time is changingfunction(date: dayjs, dateString: string)-

DatePicker[picker=month]

PropertyDescriptionTypeDefaultVersion
defaultValueTo set default datedayjs-
formatTo set the date format. refer to dayjs#formatformatTypeYYYY-MM
multipleEnable multiple selectionbooleanfalse5.14.0
renderExtraFooterRender extra footer in panel() => React.ReactNode-
valueTo set datedayjs-
onChangeCallback function, can be executed when the selected time is changingfunction(date: dayjs, dateString: string)-

DatePicker[picker=week]

PropertyDescriptionTypeDefaultVersion
defaultValueTo set default datedayjs-
formatTo set the date format. refer to dayjs#formatformatTypeYYYY-wo
multipleEnable multiple selectionbooleanfalse5.14.0
renderExtraFooterRender extra footer in panel(mode) => React.ReactNode-
valueTo set datedayjs-
onChangeCallback function, can be executed when the selected time is changingfunction(date: dayjs, dateString: string)-
showWeekShow week info when in DatePickerbooleantrue5.14.0

RangePicker

PropertyDescriptionTypeDefaultVersion
allowEmptyAllow start or end input leave empty[boolean, boolean][false, false]
cellRenderCustom 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
dateRenderCustom rendering function for date cells, >= 5.4.0 use cellRender instead.function(currentDate: dayjs, today: dayjs) => React.ReactNode-< 5.4.0
defaultPickerValueDefault panel date, will be reset when panel opendayjs-5.14.0
defaultValueTo set default date[dayjs, dayjs]-
disabledIf disable start or end[boolean, boolean]-
disabledTimeTo specify the time that cannot be selectedfunction(date: dayjs, partial: start | end, info: { from?: dayjs })-info.from: 5.17.0
formatTo set the date format. refer to dayjs#formatformatTypeYYYY-MM-DD HH:mm:ss
idConfig input ids{ start?: string, end?: string }-5.14.0
pickerValuePanel date. Used for controlled switching of panel date. Work with onPanelChangedayjs-5.14.0
presetsThe preset ranges for quick selection, Since 5.8.0, preset value supports callback function.{ label: React.ReactNode, value: (Dayjs | (() => Dayjs))[] }[]-
renderExtraFooterRender extra footer in panel() => React.ReactNode-
separatorSet separator between inputsReact.ReactNode<SwapRightOutlined />
showTimeTo provide an additional time selectionobject | booleanTimePicker Options
showTime.defaultValueTo set default time of selected date, demodayjs[][dayjs(), dayjs()]
valueTo set date[dayjs, dayjs]-
onCalendarChangeCallback function, can be executed when the start time or the end time of the range is changing. info argument is added in 4.4.0function(dates: [dayjs, dayjs], dateStrings: [string, string], info: { range:start|end })-
onChangeCallback function, can be executed when the selected time is changingfunction(dates: [dayjs, dayjs], dateStrings: [string, string])-
onFocusTrigger when get focusfunction(event, { range: 'start' | 'end' })-range: 5.14.0
onBlurTrigger when lose focusfunction(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

Design Token

Component TokenHow to use?
Token NameDescriptionTypeDefault Value
activeBgBackground color when the input box is activatedstring#ffffff
activeBorderColorActive border colorstring#1677ff
activeShadowBox-shadow when activestring0 0 0 2px rgba(5,145,255,0.1)
addonBgBackground color of addonstringrgba(0,0,0,0.02)
cellActiveWithRangeBgBackground color of cell in rangestring#e6f4ff
cellBgDisabledBackground color of disabled cellstringrgba(0,0,0,0.04)
cellHeightHeight of cellnumber24
cellHoverBgBackground color of cell hover statestringrgba(0,0,0,0.04)
cellHoverWithRangeBgBackground color of hovered cell in rangestring#cbe0fd
cellRangeBorderColorBorder color of cell in range when pickingstring#82b4f9
cellWidthWidth of cellnumber36
errorActiveShadowBox-shadow when active in error statusstring0 0 0 2px rgba(255,38,5,0.06)
hoverBgBackground color when the input box hoversstring#ffffff
hoverBorderColorHover border colorstring#4096ff
inputFontSizeFont sizenumber14
inputFontSizeLGFont size of largenumber16
inputFontSizeSMFont size of smallnumber14
multipleItemBgBackground color of multiple tagstringrgba(0,0,0,0.06)
multipleItemBorderColorBorder color of multiple tagstringtransparent
multipleItemBorderColorDisabledBorder color of multiple tag when disabledstringtransparent
multipleItemColorDisabledText color of multiple tag when disabledstringrgba(0,0,0,0.25)
multipleItemHeightHeight of multiple tagnumber24
multipleItemHeightLGHeight of multiple tag with large sizenumber32
multipleItemHeightSMHeight of multiple tag with small sizenumber16
multipleSelectorBgDisabledBackground color of multiple selector when disabledstringrgba(0,0,0,0.04)
paddingBlockVertical padding of inputnumber4
paddingBlockLGVertical padding of large inputnumber7
paddingBlockSMVertical padding of small inputnumber0
paddingInlineHorizontal padding of inputnumber11
paddingInlineLGHorizontal padding of large inputnumber11
paddingInlineSMHorizontal padding of small inputnumber7
presetsMaxWidthMax width of preset areanumber200
presetsWidthWidth of preset areanumber120
textHeightHeight of cell textnumber40
timeCellHeightHeight of time cellnumber28
timeColumnHeightHeight of time columnnumber224
timeColumnWidthWidth of time columnnumber56
warningActiveShadowBox-shadow when active in warning statusstring0 0 0 2px rgba(255,215,5,0.1)
withoutTimeCellHeightHeight of decade/year/quarter/month/week cellnumber66
zIndexPopupz-index of popupnumber1050
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.

Date-related components locale is not working?

See FAQ Date-related-components-locale-is-not-working?

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
js
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.

Basic

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Multiple

Multiple selections. Does not support showTime and picker="time".

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.14.0
Switchable picker

Switch in different types of pickers by Select.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Choose Time

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Limit Date Range

Limit the range of available dates by using minDate and maxDate.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.14.0
Disabled Date & Time

Disable specific dates and times by using disabledDate and disabledTime respectively, and disabledTime only works with showTime.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Select range dates

Using info.from of disabledDate to limit the dynamic date range selection.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Extra Footer

Render extra footer in panel for customized requirements.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Customized Cell Rendering

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
External use panel

Custom menu, external selection panel.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Status

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Placement

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Range Picker

Set range picker type by picker prop.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Need Confirm

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.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
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.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
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.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.14.0
Disabled

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Allow Empty

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Preset Ranges

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Three Sizes

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Customize Panel

Replace panel with components.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.14.0
Buddhist Era

Use locale to support special calendar format.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.14.0
Variants

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

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.13.0
Prefix and Suffix

Custom prefix and suffixIcon.

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
+ 2 ...
+ 2 ...
+ 2 ...
Time
7 days range
6 months range
2025-05-07




By locale props

By ConfigProvider

ab
ab
ab
ab
Event Period
Event Period
  • root
    5.25.0
    Root element
  • popup.root
    5.25.0
    Popup root element