Basic
Range Picker
Switchable picker
Date Format
Choose Time
Disabled
Disabled Date & Time
Select range dates in 7 days
Preset Ranges
Extra Footer
Three Sizes
Customized Date Rendering
Status
Bordered-less
Placement
API

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.

TypeScript
JavaScript
import type { DatePickerProps } from 'antd';
import { DatePicker, Space } from 'antd';
import React from 'react';

const onChange: DatePickerProps['onChange'] = (date, dateString) => {
  console.log(date, dateString);
};

const App: React.FC = () => (
  <Space direction="vertical">
    <DatePicker onChange={onChange} />
    <DatePicker onChange={onChange} picker="week" />
    <DatePicker onChange={onChange} picker="month" />
    <DatePicker onChange={onChange} picker="quarter" />
    <DatePicker onChange={onChange} picker="year" />
  </Space>
);

export default App;

Time

Switchable picker

Switch in different types of pickers by Select.

TypeScript
JavaScript
import type { DatePickerProps, TimePickerProps } from 'antd';
import { DatePicker, Select, Space, TimePicker } from 'antd';
import React, { useState } from 'react';

const { Option } = Select;

type PickerType = 'time' | 'date';

const PickerWithType = ({
  type,
  onChange,
}: {
  type: PickerType;
  onChange: TimePickerProps['onChange'] | DatePickerProps['onChange'];
}) => {
  if (type === 'time') return <TimePicker onChange={onChange} />;
  if (type === 'date') return <DatePicker onChange={onChange} />;
  return <DatePicker picker={type} onChange={onChange} />;
};

const App: React.FC = () => {
  const [type, setType] = useState<PickerType>('time');

  return (
    <Space>
      <Select value={type} onChange={setType}>
        <Option value="time">Time</Option>
        <Option value="date">Date</Option>
        <Option value="week">Week</Option>
        <Option value="month">Month</Option>
        <Option value="quarter">Quarter</Option>
        <Option value="year">Year</Option>
      </Select>
      <PickerWithType type={type} onChange={value => console.log(value)} />
    </Space>
  );
};

export default App;

Choose Time

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

TypeScript
JavaScript
import { DatePicker, Space } from 'antd';
import type { DatePickerProps, RangePickerProps } from 'antd/es/date-picker';
import React from 'react';

const { RangePicker } = DatePicker;

const onChange = (
  value: DatePickerProps['value'] | RangePickerProps['value'],
  dateString: [string, string] | string,
) => {
  console.log('Selected Time: ', value);
  console.log('Formatted Selected Time: ', dateString);
};

const onOk = (value: DatePickerProps['value'] | RangePickerProps['value']) => {
  console.log('onOk: ', value);
};

const App: React.FC = () => (
  <Space direction="vertical" size={12}>
    <DatePicker showTime onChange={onChange} onOk={onOk} />
    <RangePicker
      showTime={{ format: 'HH:mm' }}
      format="YYYY-MM-DD HH:mm"
      onChange={onChange}
      onOk={onOk}
    />
  </Space>
);

export default App;

Disabled Date & Time

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

TypeScript
JavaScript
import { DatePicker, Space } from 'antd';
import type { RangePickerProps } from 'antd/es/date-picker';
import moment from 'moment';
import React from 'react';

const { RangePicker } = DatePicker;

const range = (start: number, end: number) => {
  const result = [];
  for (let i = start; i < end; i++) {
    result.push(i);
  }
  return result;
};

// eslint-disable-next-line arrow-body-style
const disabledDate: RangePickerProps['disabledDate'] = current => {
  // Can not select days before today and today
  return current && current < moment().endOf('day');
};

const disabledDateTime = () => ({
  disabledHours: () => range(0, 24).splice(4, 20),
  disabledMinutes: () => range(30, 60),
  disabledSeconds: () => [55, 56],
});

const disabledRangeTime: RangePickerProps['disabledTime'] = (_, type) => {
  if (type === 'start') {
    return {
      disabledHours: () => range(0, 60).splice(4, 20),
      disabledMinutes: () => range(30, 60),
      disabledSeconds: () => [55, 56],
    };
  }
  return {
    disabledHours: () => range(0, 60).splice(20, 4),
    disabledMinutes: () => range(0, 31),
    disabledSeconds: () => [55, 56],
  };
};

const App: React.FC = () => (
  <Space direction="vertical" size={12}>
    <DatePicker
      format="YYYY-MM-DD HH:mm:ss"
      disabledDate={disabledDate}
      disabledTime={disabledDateTime}
      showTime={{ defaultValue: moment('00:00:00', 'HH:mm:ss') }}
    />
    <DatePicker picker="month" disabledDate={disabledDate} />
    <RangePicker disabledDate={disabledDate} />
    <RangePicker
      disabledDate={disabledDate}
      disabledTime={disabledRangeTime}
      showTime={{
        hideDisabledOptions: true,
        defaultValue: [moment('00:00:00', 'HH:mm:ss'), moment('11:59:59', 'HH:mm:ss')],
      }}
      format="YYYY-MM-DD HH:mm:ss"
    />
  </Space>
);

export default App;

Preset Ranges

We can set preset ranges to RangePicker to improve user experience.

TypeScript
JavaScript
import { DatePicker, Space } from 'antd';
import type { RangePickerProps } from 'antd/es/date-picker';
import moment from 'moment';
import React from 'react';

const { RangePicker } = DatePicker;

const onChange: RangePickerProps['onChange'] = (dates, dateStrings) => {
  if (dates) {
    console.log('From: ', dates[0], ', to: ', dates[1]);
    console.log('From: ', dateStrings[0], ', to: ', dateStrings[1]);
  } else {
    console.log('Clear');
  }
};

const App: React.FC = () => (
  <Space direction="vertical" size={12}>
    <RangePicker
      ranges={{
        Today: [moment(), moment()],
        'This Month': [moment().startOf('month'), moment().endOf('month')],
      }}
      onChange={onChange}
    />
    <RangePicker
      ranges={{
        Today: [moment(), moment()],
        'This Month': [moment().startOf('month'), moment().endOf('month')],
      }}
      showTime
      format="YYYY/MM/DD HH:mm:ss"
      onChange={onChange}
    />
  </Space>
);

export default App;

LargemiddleSmall

Three Sizes

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

TypeScript
JavaScript
import type { RadioChangeEvent } from 'antd';
import { DatePicker, Radio, Space } from 'antd';
import type { SizeType } from 'antd/es/config-provider/SizeContext';
import React, { useState } from 'react';

const { RangePicker } = DatePicker;

const App: React.FC = () => {
  const [size, setSize] = useState<SizeType>('middle');

  const handleSizeChange = (e: RadioChangeEvent) => {
    setSize(e.target.value);
  };

  return (
    <Space direction="vertical" size={12}>
      <Radio.Group value={size} onChange={handleSizeChange}>
        <Radio.Button value="large">Large</Radio.Button>
        <Radio.Button value="middle">middle</Radio.Button>
        <Radio.Button value="small">Small</Radio.Button>
      </Radio.Group>
      <DatePicker size={size} />
      <DatePicker size={size} picker="month" />
      <RangePicker size={size} />
      <DatePicker size={size} picker="week" />
    </Space>
  );
};

export default App;

Status

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

TypeScript
JavaScript
import { DatePicker, Space } from 'antd';
import React from 'react';

const App: React.FC = () => (
  <Space direction="vertical" style={{ width: '100%' }}>
    <DatePicker status="error" style={{ width: '100%' }} />
    <DatePicker status="warning" style={{ width: '100%' }} />
    <DatePicker.RangePicker status="error" style={{ width: '100%' }} />
    <DatePicker.RangePicker status="warning" style={{ width: '100%' }} />
  </Space>
);

export default App;

4.19.0

topLefttopRightbottomLeftbottomRight

Placement

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

TypeScript
JavaScript
import type { DatePickerProps, RadioChangeEvent } from 'antd';
import { DatePicker, Radio } from 'antd';
import React, { useState } from 'react';

const { RangePicker } = DatePicker;

const App: React.FC = () => {
  const [placement, SetPlacement] = useState<DatePickerProps['placement']>('topLeft');

  const placementChange = (e: RadioChangeEvent) => {
    SetPlacement(e.target.value);
  };

  return (
    <>
      <Radio.Group value={placement} onChange={placementChange}>
        <Radio.Button value="topLeft">topLeft</Radio.Button>
        <Radio.Button value="topRight">topRight</Radio.Button>
        <Radio.Button value="bottomLeft">bottomLeft</Radio.Button>
        <Radio.Button value="bottomRight">bottomRight</Radio.Button>
      </Radio.Group>
      <br />
      <br />
      <DatePicker placement={placement} />
      <br />
      <br />
      <RangePicker placement={placement} />
    </>
  );
};

export default App;

Range Picker

Set range picker type by picker prop.

TypeScript
JavaScript
import { DatePicker, Space } from 'antd';
import React from 'react';

const { RangePicker } = DatePicker;

const App: React.FC = () => (
  <Space direction="vertical" size={12}>
    <RangePicker />
    <RangePicker showTime />
    <RangePicker picker="week" />
    <RangePicker picker="month" />
    <RangePicker picker="quarter" />
    <RangePicker picker="year" />
  </Space>
);

export default App;

Date Format

We can set the date format by format.

TypeScript
JavaScript
import type { DatePickerProps } from 'antd';
import { DatePicker, Space } from 'antd';
import moment from 'moment';
import React from 'react';

const { RangePicker } = DatePicker;

const dateFormat = 'YYYY/MM/DD';
const weekFormat = 'MM/DD';
const monthFormat = 'YYYY/MM';

const dateFormatList = ['DD/MM/YYYY', 'DD/MM/YY'];

const customFormat: DatePickerProps['format'] = value =>
  `custom format: ${value.format(dateFormat)}`;

const customWeekStartEndFormat: DatePickerProps['format'] = value =>
  `${moment(value).startOf('week').format(weekFormat)} ~ ${moment(value)
    .endOf('week')
    .format(weekFormat)}`;

const App: React.FC = () => (
  <Space direction="vertical" size={12}>
    <DatePicker defaultValue={moment('2015/01/01', dateFormat)} format={dateFormat} />
    <DatePicker defaultValue={moment('01/01/2015', dateFormatList[0])} format={dateFormatList} />
    <DatePicker defaultValue={moment('2015/01', monthFormat)} format={monthFormat} picker="month" />
    <DatePicker defaultValue={moment()} format={customWeekStartEndFormat} picker="week" />
    <RangePicker
      defaultValue={[moment('2015/01/01', dateFormat), moment('2015/01/01', dateFormat)]}
      format={dateFormat}
    />
    <DatePicker defaultValue={moment('2015/01/01', dateFormat)} format={customFormat} />
  </Space>
);

export default App;

Disabled

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

TypeScript
JavaScript
import { DatePicker, Space } from 'antd';
import moment from 'moment';
import React from 'react';

const { RangePicker } = DatePicker;

const dateFormat = 'YYYY-MM-DD';

const App: React.FC = () => (
  <Space direction="vertical" size={12}>
    <DatePicker defaultValue={moment('2015-06-06', dateFormat)} disabled />
    <DatePicker picker="month" defaultValue={moment('2015-06', 'YYYY-MM')} disabled />
    <RangePicker
      defaultValue={[moment('2015-06-06', dateFormat), moment('2015-06-06', dateFormat)]}
      disabled
    />
    <RangePicker
      defaultValue={[moment('2019-09-03', dateFormat), moment('2019-11-22', dateFormat)]}
      disabled={[false, true]}
    />
  </Space>
);

export default App;

Select range dates in 7 days

A example shows how to select a dynamic range by using onCalendarChange and disabledDate.

TypeScript
JavaScript
import { DatePicker } from 'antd';
import type { Moment } from 'moment';
import React, { useState } from 'react';

const { RangePicker } = DatePicker;

type RangeValue = [Moment | null, Moment | null] | null;

const App: React.FC = () => {
  const [dates, setDates] = useState<RangeValue>(null);
  const [value, setValue] = useState<RangeValue>(null);

  const disabledDate = (current: Moment) => {
    if (!dates) {
      return false;
    }
    const tooLate = dates[0] && current.diff(dates[0], 'days') > 7;
    const tooEarly = dates[1] && dates[1].diff(current, 'days') > 7;
    return !!tooEarly || !!tooLate;
  };

  const onOpenChange = (open: boolean) => {
    if (open) {
      setDates([null, null]);
    } else {
      setDates(null);
    }
  };

  return (
    <RangePicker
      value={dates || value}
      disabledDate={disabledDate}
      onCalendarChange={val => setDates(val)}
      onChange={val => setValue(val)}
      onOpenChange={onOpenChange}
      onBlur={() => console.log('blur has been triggered')}
    />
  );
};

export default App;

Extra Footer

Render extra footer in panel for customized requirements.

TypeScript
JavaScript
import { DatePicker, Space } from 'antd';
import React from 'react';

const { RangePicker } = DatePicker;

const App: React.FC = () => (
  <Space direction="vertical" size={12}>
    <DatePicker renderExtraFooter={() => 'extra footer'} />
    <DatePicker renderExtraFooter={() => 'extra footer'} showTime />
    <RangePicker renderExtraFooter={() => 'extra footer'} />
    <RangePicker renderExtraFooter={() => 'extra footer'} showTime />
    <DatePicker renderExtraFooter={() => 'extra footer'} picker="month" />
  </Space>
);

export default App;

Customized Date Rendering

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

TypeScript
JavaScript
import { DatePicker, Space } from 'antd';
import React from 'react';

const { RangePicker } = DatePicker;

const App: React.FC = () => (
  <Space direction="vertical" size={12}>
    <DatePicker
      dateRender={current => {
        const style: React.CSSProperties = {};
        if (current.date() === 1) {
          style.border = '1px solid #1890ff';
          style.borderRadius = '50%';
        }
        return (
          <div className="ant-picker-cell-inner" style={style}>
            {current.date()}
          </div>
        );
      }}
    />
    <RangePicker
      dateRender={current => {
        const style: React.CSSProperties = {};
        if (current.date() === 1) {
          style.border = '1px solid #1890ff';
          style.borderRadius = '50%';
        }
        return (
          <div className="ant-picker-cell-inner" style={style}>
            {current.date()}
          </div>
        );
      }}
    />
  </Space>
);

export default App;

Bordered-less

Bordered-less style component.

TypeScript
JavaScript
import { DatePicker, Space } from 'antd';
import React from 'react';

const { RangePicker } = DatePicker;

const App: React.FC = () => (
  <Space direction="vertical" size={12}>
    <DatePicker bordered={false} />
    <DatePicker picker="week" bordered={false} />
    <DatePicker picker="month" bordered={false} />
    <DatePicker picker="year" bordered={false} />
    <RangePicker bordered={false} />
    <RangePicker picker="week" bordered={false} />
    <RangePicker picker="month" bordered={false} />
    <RangePicker picker="year" bordered={false} />
  </Space>
);

export default App;

API#

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 'moment/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 moment from 'moment';
import 'moment/locale/zh-cn';
import locale from 'antd/es/locale/zh_CN';

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

Common API#

The following APIs are shared by DatePicker, RangePicker.

Property	Description	Type	Default	Version
allowClear	Whether to show clear button	boolean	true
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	function(currentDate: moment, today: moment) => React.ReactNode	-
disabled	Determine whether the DatePicker is disabled	boolean	false
disabledDate	Specify the date that cannot be selected	(currentDate: moment) => boolean	-
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	{}
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	moment	-
defaultValue	To set default date, if start time or end time is null or undefined, the date range will be an open interval	moment	-
disabledTime	To specify the time that cannot be selected	function(date)	-
format	To set the date format, refer to moment.js. When an array is provided, all values are used for parsing and first value is used for formatting, support Custom Format	string \| (value: moment) => string \| (string \| (value: moment) => string)[]	`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	moment	moment()
showToday	Whether to show `Today` button	boolean	true
value	To set date	moment	-
onChange	Callback function, can be executed when the selected time is changing	function(date: moment, 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	moment	-
defaultValue	To set default date	moment	-
format	To set the date format, refer to moment.js	string	`YYYY`
renderExtraFooter	Render extra footer in panel	() => React.ReactNode	-
value	To set date	moment	-
onChange	Callback function, can be executed when the selected time is changing	function(date: moment, dateString: string)	-

DatePicker[picker=quarter]#

Added in 4.1.0.

Property	Description	Type	Default
defaultPickerValue	To set default picker date	moment	-
defaultValue	To set default date	moment	-
format	To set the date format, refer to moment.js	string	`YYYY-\QQ`
renderExtraFooter	Render extra footer in panel	() => React.ReactNode	-
value	To set date	moment	-
onChange	Callback function, can be executed when the selected time is changing	function(date: moment, dateString: string)	-

DatePicker[picker=month]#

Property	Description	Type	Default
defaultPickerValue	To set default picker date	moment	-
defaultValue	To set default date	moment	-
format	To set the date format, refer to moment.js	string	`YYYY-MM`
monthCellRender	Custom month cell content render method	function(date, locale): ReactNode	-
renderExtraFooter	Render extra footer in panel	() => React.ReactNode	-
value	To set date	moment	-
onChange	Callback function, can be executed when the selected time is changing	function(date: moment, dateString: string)	-

DatePicker[picker=week]#

Property	Description	Type	Default
defaultPickerValue	To set default picker date	moment	-
defaultValue	To set default date	moment	-
format	To set the date format, refer to moment.js	string	`YYYY-wo`
renderExtraFooter	Render extra footer in panel	(mode) => React.ReactNode	-
value	To set date	moment	-
onChange	Callback function, can be executed when the selected time is changing	function(date: moment, dateString: string)	-

RangePicker#

Property	Description	Type	Default
allowEmpty	Allow start or end input leave empty	[boolean, boolean]	[false, false]
dateRender	Customize date cell. `info` argument is added in 4.3.0	function(currentDate: moment, today: moment, info: { range: `start` \| `end` }) => React.ReactNode	-
defaultPickerValue	To set default picker date	[moment, moment]	-
defaultValue	To set default date	[moment, moment]	-
disabled	If disable start or end	[boolean, boolean]	-
disabledTime	To specify the time that cannot be selected	function(date: moment, partial: `start` \| `end`)	-
format	To set the date format, refer to moment.js. When an array is provided, all values are used for parsing and first value is used for formatting	string \| string[]	`YYYY-MM-DD HH:mm:ss`
ranges	The preseted ranges for quick selection	{ [range: string]: moment[] } \| { [range: string]: () => moment[] }	-
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	moment[]	[moment(), moment()]
value	To set date	[moment, moment]	-
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: [moment, moment], dateStrings: [string, string], info: { range:`start`\|`end` })	-
onChange	Callback function, can be executed when the selected time is changing	function(dates: [moment, moment], dateStrings: [string, string])	-

FAQ#

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

Please refer FAQ

How to use DatePicker with customize date library like dayjs?#

Please refer replace moment

Why config moment.locale globally not work?#

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

How to modify start day of week?#

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

Example: https://codesandbox.io/s/moment-day-of-week-6dby5
Alternate example: https://stackblitz.com/edit/react-9aegkj

moment.locale('en', {
  week: {
    dow: 1,
  },
});

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.