By clicking the input box, you can select a date from a popup calendar.
Basic use case. Users can select or input a date in panel.
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;
Switch in different types of pickers by Select.
import React, { useState } from 'react';
import type { DatePickerProps, TimePickerProps } from 'antd';
import { DatePicker, Select, Space, TimePicker } from 'antd';
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;
This property provide an additional time selection. When showTime is an Object, its properties will be passed on to built-in TimePicker.
import React from 'react';
import { DatePicker, Space } from 'antd';
import type { DatePickerProps, RangePickerProps } from 'antd/es/date-picker';
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 part of dates and time by disabledDate and disabledTime respectively, and disabledTime only works with showTime.
import React from 'react';
import { DatePicker, Space } from 'antd';
import type { RangePickerProps } from 'antd/es/date-picker';
import dayjs from 'dayjs';
import customParseFormat from 'dayjs/plugin/customParseFormat';
dayjs.extend(customParseFormat);
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 < dayjs().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: dayjs('00:00:00', 'HH:mm:ss') }}
/>
<DatePicker picker="month" disabledDate={disabledDate} />
<RangePicker disabledDate={disabledDate} />
<RangePicker
disabledDate={disabledDate}
disabledTime={disabledRangeTime}
showTime={{
hideDisabledOptions: true,
defaultValue: [dayjs('00:00:00', 'HH:mm:ss'), dayjs('11:59:59', 'HH:mm:ss')],
}}
format="YYYY-MM-DD HH:mm:ss"
/>
</Space>
);
export default App;
We can set preset ranges to RangePicker to improve user experience.
import React from 'react';
import { DatePicker, Space } from 'antd';
import dayjs from 'dayjs';
import type { Dayjs } from 'dayjs';
const { RangePicker } = DatePicker;
const onChange = (date: Dayjs) => {
if (date) {
console.log('Date: ', date);
} else {
console.log('Clear');
}
};
const onRangeChange = (dates: null | (Dayjs | null)[], dateStrings: string[]) => {
if (dates) {
console.log('From: ', dates[0], ', to: ', dates[1]);
console.log('From: ', dateStrings[0], ', to: ', dateStrings[1]);
} else {
console.log('Clear');
}
};
const rangePresets: {
label: string;
value: [Dayjs, Dayjs];
}[] = [
{ label: 'Last 7 Days', value: [dayjs().add(-7, 'd'), dayjs()] },
{ label: 'Last 14 Days', value: [dayjs().add(-14, 'd'), dayjs()] },
{ label: 'Last 30 Days', value: [dayjs().add(-30, 'd'), dayjs()] },
{ label: 'Last 90 Days', value: [dayjs().add(-90, 'd'), dayjs()] },
];
const App: React.FC = () => (
<Space direction="vertical" size={12}>
<DatePicker
presets={[
{ label: 'Yesterday', value: dayjs().add(-1, 'd') },
{ label: 'Last Week', value: dayjs().add(-7, 'd') },
{ label: 'Last Month', value: dayjs().add(-1, 'month') },
]}
onChange={onChange}
/>
<RangePicker presets={rangePresets} onChange={onRangeChange} />
<RangePicker
presets={rangePresets}
showTime
format="YYYY/MM/DD HH:mm:ss"
onChange={onRangeChange}
/>
</Space>
);
export default App;
The input box comes in three sizes. middle will be used if size is omitted.
import React, { useState } from 'react';
import type { RadioChangeEvent } from 'antd';
import { DatePicker, Radio, Space } from 'antd';
import type { SizeType } from 'antd/es/config-provider/SizeContext';
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;
Add status to DatePicker with status, which could be error or warning.
import React from 'react';
import { DatePicker, Space } from 'antd';
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;
You can manually specify the position of the popup via placement.
import React, { useState } from 'react';
import type { DatePickerProps, RadioChangeEvent } from 'antd';
import { DatePicker, Radio } from 'antd';
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;
Set range picker type by picker prop.
import React from 'react';
import { DatePicker, Space } from 'antd';
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;
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.
import React from 'react';
import type { DatePickerProps } from 'antd';
import { DatePicker, Space } from 'antd';
import dayjs from 'dayjs';
import customParseFormat from 'dayjs/plugin/customParseFormat';
dayjs.extend(customParseFormat);
const { RangePicker } = DatePicker;
const dateFormat = 'YYYY/MM/DD';
const weekFormat = 'MM/DD';
const monthFormat = 'YYYY/MM';
/** Manually entering any of the following formats will perform date parsing */
const dateFormatList = ['DD/MM/YYYY', 'DD/MM/YY', 'DD-MM-YYYY', 'DD-MM-YY'];
const customFormat: DatePickerProps['format'] = (value) =>
`custom format: ${value.format(dateFormat)}`;
const customWeekStartEndFormat: DatePickerProps['format'] = (value) =>
`${dayjs(value).startOf('week').format(weekFormat)} ~ ${dayjs(value)
.endOf('week')
.format(weekFormat)}`;
const App: React.FC = () => (
<Space direction="vertical" size={12}>
<DatePicker defaultValue={dayjs('2015/01/01', dateFormat)} format={dateFormat} />
<DatePicker defaultValue={dayjs('01/01/2015', dateFormatList[0])} format={dateFormatList} />
<DatePicker defaultValue={dayjs('2015/01', monthFormat)} format={monthFormat} picker="month" />
<DatePicker defaultValue={dayjs()} format={customWeekStartEndFormat} picker="week" />
<RangePicker
defaultValue={[dayjs('2015/01/01', dateFormat), dayjs('2015/01/01', dateFormat)]}
format={dateFormat}
/>
<DatePicker defaultValue={dayjs('2015/01/01', dateFormat)} format={customFormat} />
</Space>
);
export default App;
A disabled state of the DatePicker. You can also set as array to disable one of input.
import React from 'react';
import { DatePicker, Space } from 'antd';
import dayjs from 'dayjs';
import customParseFormat from 'dayjs/plugin/customParseFormat';
dayjs.extend(customParseFormat);
const { RangePicker } = DatePicker;
const dateFormat = 'YYYY-MM-DD';
const App: React.FC = () => (
<Space direction="vertical" size={12}>
<DatePicker defaultValue={dayjs('2015-06-06', dateFormat)} disabled />
<DatePicker picker="month" defaultValue={dayjs('2015-06', 'YYYY-MM')} disabled />
<RangePicker
defaultValue={[dayjs('2015-06-06', dateFormat), dayjs('2015-06-06', dateFormat)]}
disabled
/>
<RangePicker
defaultValue={[dayjs('2019-09-03', dateFormat), dayjs('2019-11-22', dateFormat)]}
disabled={[false, true]}
/>
</Space>
);
export default App;
A example shows how to select a dynamic range by using onCalendarChange and disabledDate.
import React, { useState } from 'react';
import { DatePicker } from 'antd';
import type { Dayjs } from 'dayjs';
const { RangePicker } = DatePicker;
type RangeValue = [Dayjs | null, Dayjs | null] | null;
const App: React.FC = () => {
const [dates, setDates] = useState<RangeValue>(null);
const [value, setValue] = useState<RangeValue>(null);
const disabledDate = (current: Dayjs) => {
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}
/>
);
};
export default App;
Render extra footer in panel for customized requirements.
import React from 'react';
import { DatePicker, Space } from 'antd';
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;
We can customize the rendering of date cells in the calendar by providing a dateRender function to DatePicker.
import React from 'react';
import { DatePicker, Space } from 'antd';
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 style component.
import React from 'react';
import { DatePicker, Space } from 'antd';
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;
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.
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>;
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: dayjs, today: dayjs) => React.ReactNode | - | |
| 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 | { label: React.ReactNode, value: 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) | - |
| Name | Description | Version |
|---|---|---|
| blur() | Remove focus | |
| focus() | Get focus |
| 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) | - |
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| 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) | - |
Added in 4.1.0.
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| 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) | - |
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| 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 | |
| monthCellRender | Custom month cell content render method | function(date, locale): ReactNode | - | |
| 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 |
|---|---|---|---|---|
| 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) | - |
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
| 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: dayjs, today: dayjs, info: { range: start | end }) => React.ReactNode | - | |
| 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 | { label: React.ReactNode, value: 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]) | - |
import type { Dayjs } from 'dayjs';type Generic = string;type GenericFn = (value: Dayjs) => string;export type FormatType = Generic | GenericFn | Array<Generic | GenericFn>;
Please refer FAQ
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 'dayjs/plugin/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.