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 use case. Users can select or input a date in panel.

import { DatePicker } from 'antd';
const { MonthPicker, RangePicker } = DatePicker;

function onChange(date, dateString) {
  console.log(date, dateString);
}

ReactDOM.render(
  <div>
    <DatePicker onChange={onChange} />
    <br />
    <MonthPicker onChange={onChange} placeholder="Select month" />
    <br />
    <RangePicker onChange={onChange} />
  </div>
, mountNode);




~

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

import { DatePicker, Radio } from 'antd';
const { MonthPicker, RangePicker } = DatePicker;

class PickerSizesDemo extends React.Component {
  state = {
    size: 'default',
  };

  handleSizeChange = (e) => {
    this.setState({ size: e.target.value });
  }

  render() {
    const { size } = this.state;
    return (
      <div>
        <Radio.Group value={size} onChange={this.handleSizeChange}>
          <Radio.Button value="large">Large</Radio.Button>
          <Radio.Button value="default">Default</Radio.Button>
          <Radio.Button value="small">Small</Radio.Button>
        </Radio.Group>
        <br /><br />
        <DatePicker size={size} />
        <br />
        <MonthPicker size={size} />
        <br />
        <RangePicker size={size} />
      </div>
    );
  }
}

ReactDOM.render(<PickerSizesDemo />, mountNode);


~

A disabled state of the DatePicker.

import { DatePicker } from 'antd';
import moment from 'moment';
const { MonthPicker, RangePicker } = DatePicker;

const dateFormat = 'YYYY-MM-DD';
ReactDOM.render(
  <div>
    <DatePicker defaultValue={moment('2015-06-06', dateFormat)} disabled />
    <br />
    <MonthPicker defaultValue={moment('2015-06', 'YYYY-MM')} disabled />
    <br />
    <RangePicker
      defaultValue={[moment('2015-06-06', dateFormat), moment('2015-06-06', dateFormat)]}
      disabled
    />
  </div>
, mountNode);

When RangePicker is not satisfied your requirements, try to implement similar functionality with two DatePicker.

  • Use the disabledDate property to limit the start and end dates.

  • Imporve user experience with open onOpenChange.

import { DatePicker } from 'antd';

class DateRange extends React.Component {
  state = {
    startValue: null,
    endValue: null,
    endOpen: false,
  };

  disabledStartDate = (startValue) => {
    const endValue = this.state.endValue;
    if (!startValue || !endValue) {
      return false;
    }
    return startValue.valueOf() > endValue.valueOf();
  }

  disabledEndDate = (endValue) => {
    const startValue = this.state.startValue;
    if (!endValue || !startValue) {
      return false;
    }
    return endValue.valueOf() <= startValue.valueOf();
  }

  onChange = (field, value) => {
    this.setState({
      [field]: value,
    });
  }

  onStartChange = (value) => {
    this.onChange('startValue', value);
  }

  onEndChange = (value) => {
    this.onChange('endValue', value);
  }

  handleStartOpenChange = (open) => {
    if (!open) {
      this.setState({ endOpen: true });
    }
  }

  handleEndOpenChange = (open) => {
    this.setState({ endOpen: open });
  }

  render() {
    const { startValue, endValue, endOpen } = this.state;
    return (
      <div>
        <DatePicker
          disabledDate={this.disabledStartDate}
          showTime
          format="YYYY-MM-DD HH:mm:ss"
          value={startValue}
          placeholder="Start"
          onChange={this.onStartChange}
          onOpenChange={this.handleStartOpenChange}
        />
        <DatePicker
          disabledDate={this.disabledEndDate}
          showTime
          format="YYYY-MM-DD HH:mm:ss"
          value={endValue}
          placeholder="End"
          onChange={this.onEndChange}
          open={endOpen}
          onOpenChange={this.handleEndOpenChange}
        />
      </div>
    );
  }
}

ReactDOM.render(<DateRange />, mountNode);


~

We can set the date format by format.

import { DatePicker } from 'antd';
import moment from 'moment';
const { MonthPicker, RangePicker } = DatePicker;

const dateFormat = 'YYYY/MM/DD';
const monthFormat = 'YYYY/MM';
ReactDOM.render(
  <div>
    <DatePicker defaultValue={moment('2015/01/01', dateFormat)} format={dateFormat} />
    <br />
    <MonthPicker defaultValue={moment('2015/01', monthFormat)} format={monthFormat} />
    <br />
    <RangePicker
      defaultValue={[moment('2015/01/01', dateFormat), moment('2015/01/01', dateFormat)]}
      format={dateFormat}
    />
  </div>
, mountNode);

~

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

import { DatePicker } from 'antd';
const { RangePicker } = DatePicker;

function onChange(value, dateString) {
  console.log('Selected Time: ', value);
  console.log('Formatted Selected Time: ', dateString);
}

function onOk(value) {
  console.log('onOk: ', value);
}

ReactDOM.render(
  <div>
    <DatePicker
      showTime
      format="YYYY-MM-DD HH:mm:ss"
      placeholder="Select Time"
      onChange={onChange}
      onOk={onOk}
    />
    <br />
    <RangePicker
      showTime={{ format: 'HH:mm' }}
      format="YYYY-MM-DD HH:mm"
      placeholder={['Start Time', 'End Time']}
      onChange={onChange}
      onOk={onOk}
    />
  </div>
, mountNode);


~

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

import moment from 'moment';
import { DatePicker } from 'antd';
const { MonthPicker, RangePicker } = DatePicker;

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

function disabledDate(current) {
  // Can not select days before today and today
  return current && current.valueOf() < Date.now();
}

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

function disabledRangeTime(_, 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],
  };
}

ReactDOM.render(
  <div>
    <DatePicker
      format="YYYY-MM-DD HH:mm:ss"
      disabledDate={disabledDate}
      disabledTime={disabledDateTime}
      showTime={{ defaultValue: moment('00:00:00', 'HH:mm:ss') }}
    />
    <br />
    <MonthPicker disabledDate={disabledDate} placeholder="Select month" />
    <br />
    <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"
    />
  </div>,
  mountNode
);
~
~

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

import { DatePicker } from 'antd';
import moment from 'moment';
const RangePicker = DatePicker.RangePicker;

function onChange(dates, dateStrings) {
  console.log('From: ', dates[0], ', to: ', dates[1]);
  console.log('From: ', dateStrings[0], ', to: ', dateStrings[1]);
}

ReactDOM.render(
  <div>
    <RangePicker
      ranges={{ Today: [moment(), moment()], 'This Month': [moment(), moment().endOf('month')] }}
      onChange={onChange}
    />
    <br />
    <RangePicker
      ranges={{ Today: [moment(), moment()], 'This Month': [moment(), moment().endOf('month')] }}
      showTime
      format="YYYY/MM/DD HH:mm:ss"
      onChange={onChange}
    />
  </div>,
  mountNode
);

API#

There are three kinds of picker:

  • DatePicker

  • MonthPicker

  • RangePicker

Note: Part of locale of DatePicker, MonthPicker, RangePicker is read from value. So, please set the locale of moment correctly.

import moment from 'moment';

// It's recommended to set locale in entry file globaly.
import 'moment/locale/zh-cn';
moment.locale('zh-cn');

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

Common API#

The following APIs are shared by DatePicker, MonthPicker, RangePicker.

PropertyDescriptionTypeDefault
allowClearWhether to show clear buttonbooleantrue
disableddetermine whether the DatePicker is disabledbooleanfalse
classNamepicker classNamestring''
styleto customize the style of the input boxobject{}
popupStyleto customize the style of the popup calendarobject{}
sizedetermine the size of the input box, the height of large and small, are 32px and 22px respectively, while default size is 28pxstring-
localelocalization configurationobjectdefault
disabledDatespecify the date that cannot be selected(currentDate: moment) => boolean-
getCalendarContainerto set the container of the floating layer, while the default is to create a div element in bodyfunction(trigger)-
openopen state of pickerboolean-
onOpenChangea callback function, can be executed whether the popup calendar is popped up or closedfunction(status)-
placeholderplaceholder of date inputstring|RangePicker[]-

DatePicker#

PropertyDescriptionTypeDefault
valueto set datemoment-
defaultValueto set default datemoment-
formatto set the date format, refer to moment.jsstring"YYYY-MM-DD"
onChangea callback function, can be executed when the selected time is changingfunction(date: moment, dateString: string)-
showTimeto provide an additional time selectionobject|booleanTimePicker Options
showTime.defaultValueto set default time of selected date, demomomentmoment()
showTodaywhether to show "Today" buttonbooleantrue
disabledTimeto specify the time that cannot be selectedfunction(date)-
onOkcallback when click ok buttonfunction()-
renderExtraFooterrender extra footer in panel() => React.ReactNode-

MonthPicker#

PropertyDescriptionTypeDefault
valueto set datemoment-
defaultValueto set default datemoment-
formatto set the date format, refer to moment.jsstring"YYYY-MM"
onChangea callback function, can be executed when the selected time is changingfunction(date: moment, dateString: string)-
monthCellContentRenderCustom month cell content render methodfunction(date, locale): ReactNode-

RangePicker#

PropertyDescriptionTypeDefault
valueto set date[moment, moment]-
defaultValueto set default date[moment, moment]-
formatto set the date formatstring"YYYY-MM-DD HH:mm:ss"
onChangea callback function, can be executed when the selected time is changingfunction(dates: moment, moment, dateStrings: string, string)-
showTimeto provide an additional time selectionobject|booleanTimePicker Options
showTime.defaultValueto set default time of selected date, demomoment[]moment(), moment()
disabledTimeto specify the time that cannot be selectedfunction(dates: moment, moment, partial: 'start'|'end')-
rangespreseted ranges for quick selection{ range: string: moment[] }-
renderExtraFooterrender extra footer in panel() => React.ReactNode-
onOkcallback when click ok buttonfunction()-