Date Fields - ProComponents

Date field components provide various date and time selection options.

ProFormDatePicker

Date picker component for selecting a single date.

Import

import { ProFormDatePicker } from '@ant-design/pro-components';

Usage

Basic
With Format
Disabled Dates

<ProFormDatePicker
  name="birthDate"
  label="Birth Date"
  placeholder="Select date"
/>

<ProFormDatePicker
  name="startDate"
  label="Start Date"
  fieldProps={{
    format: 'YYYY/MM/DD'
  }}
/>

<ProFormDatePicker
  name="appointmentDate"
  label="Appointment Date"
  fieldProps={{
    disabledDate: (current) => {
      // Disable dates before today
      return current && current < dayjs().startOf('day');
    }
  }}
/>

Props

Extends ProFormText props and Ant Design DatePicker props.

fieldProps.format

string | string[]

default:"'YYYY-MM-DD'"

Date format for display and parsing. Common formats:

YYYY-MM-DD: 2024-03-15
MM/DD/YYYY: 03/15/2024
DD-MM-YYYY: 15-03-2024
YYYY年MM月DD日: Chinese format

fieldProps.picker

'date' | 'week' | 'month' | 'quarter' | 'year'

default:"'date'"

Type of picker. Use sub-components for other types (see below).

fieldProps.showTime

boolean | TimePickerProps

Whether to show time picker. Can provide time picker configuration.

fieldProps.showToday

boolean

default:"true"

Whether to show “Today” button.

fieldProps.showNow

boolean

default:"true"

Whether to show “Now” button (when showTime is enabled).

fieldProps.disabledDate

(currentDate: Dayjs) => boolean

Function to determine if a date should be disabled. Return true to disable the date.

fieldProps.defaultValue

Dayjs

Default date value.

fieldProps.allowClear

boolean

default:"true"

Whether to show clear button.

fieldProps.placeholder

string

Placeholder text when no date is selected.

fieldProps.onChange

(date: Dayjs | null, dateString: string) => void

Callback when selected date changes.

fieldProps.onOk

(date: Dayjs) => void

Callback when OK button is clicked (when showTime is enabled).

ProFormDatePicker.Week

Week picker component.

Import

import { ProFormDatePicker } from '@ant-design/pro-components';

Usage

<ProFormDatePicker.Week
  name="reportWeek"
  label="Report Week"
  fieldProps={{
    format: 'YYYY-wo'
  }}
/>

Props

Extends ProFormDatePicker props with week-specific settings.

fieldProps.format

string

default:"'YYYY-wo'"

Week format. Common formats:

YYYY-wo: 2024-11th
GGGG[W]WW: 2024W11

ProFormDatePicker.Month

Month picker component.

Import

import { ProFormDatePicker } from '@ant-design/pro-components';

Usage

<ProFormDatePicker.Month
  name="reportMonth"
  label="Report Month"
  fieldProps={{
    format: 'YYYY-MM'
  }}
/>

Props

Extends ProFormDatePicker props with month-specific settings.

fieldProps.format

string

default:"'YYYY-MM'"

Month format. Common formats:

YYYY-MM: 2024-03
MMM YYYY: Mar 2024
MMMM YYYY: March 2024

ProFormDatePicker.Quarter

Quarter picker component.

Import

import { ProFormDatePicker } from '@ant-design/pro-components';

Usage

<ProFormDatePicker.Quarter
  name="reportQuarter"
  label="Report Quarter"
  fieldProps={{
    format: 'YYYY-[Q]Q'
  }}
/>

Props

Extends ProFormDatePicker props with quarter-specific settings.

fieldProps.format

string

default:"'YYYY-[Q]Q'"

Quarter format. Common formats:

YYYY-[Q]Q: 2024-Q1
YYYY-Qo: 2024-1st

ProFormDatePicker.Year

Year picker component.

Import

import { ProFormDatePicker } from '@ant-design/pro-components';

Usage

<ProFormDatePicker.Year
  name="graduationYear"
  label="Graduation Year"
  fieldProps={{
    format: 'YYYY'
  }}
/>

Props

Extends ProFormDatePicker props with year-specific settings.

fieldProps.format

string

default:"'YYYY'"

Year format. Common formats:

YYYY: 2024
YY: 24

ProFormDateRangePicker

Date range picker for selecting start and end dates.

Import

import { ProFormDateRangePicker } from '@ant-design/pro-components';

Usage

Basic
With Presets
With Time

<ProFormDateRangePicker
  name="dateRange"
  label="Date Range"
  placeholder={['Start date', 'End date']}
/>

<ProFormDateRangePicker
  name="reportRange"
  label="Report Period"
  fieldProps={{
    presets: [
      { label: 'Last 7 Days', value: [dayjs().subtract(7, 'd'), dayjs()] },
      { label: 'Last 30 Days', value: [dayjs().subtract(30, 'd'), dayjs()] },
      { label: 'Last Month', value: [dayjs().subtract(1, 'month').startOf('month'), dayjs().subtract(1, 'month').endOf('month')] },
      { label: 'This Month', value: [dayjs().startOf('month'), dayjs().endOf('month')] }
    ]
  }}
/>

<ProFormDateRangePicker
  name="eventRange"
  label="Event Time Range"
  fieldProps={{
    showTime: {
      format: 'HH:mm'
    },
    format: 'YYYY-MM-DD HH:mm'
  }}
/>

Props

Extends ProFormText props and Ant Design RangePicker props.

fieldProps.format

string | string[]

default:"'YYYY-MM-DD'"

Date format for display and parsing.

fieldProps.showTime

boolean | TimeRangePickerProps

Whether to show time picker. Can provide time picker configuration:

showTime={{
  format: 'HH:mm:ss',
  defaultValue: [dayjs('00:00:00', 'HH:mm:ss'), dayjs('23:59:59', 'HH:mm:ss')]
}}

fieldProps.placeholder

[string, string]

Placeholder for start and end date inputs.

fieldProps.disabledDate

(currentDate: Dayjs, info: { from?: Dayjs, type: 'start' | 'end' }) => boolean

Function to determine if a date should be disabled.

fieldProps.presets

{ label: string, value: [Dayjs, Dayjs] }[]

Preset date ranges for quick selection:

presets={[
  { label: 'Today', value: [dayjs(), dayjs()] },
  { label: 'This Week', value: [dayjs().startOf('week'), dayjs().endOf('week')] }
]}

fieldProps.separator

ReactNode

default:"'~'"

Separator between start and end date inputs.

fieldProps.allowEmpty

[boolean, boolean]

Whether to allow clearing start or end date independently.

fieldProps.onChange

(dates: [Dayjs | null, Dayjs | null], dateStrings: [string, string]) => void

Callback when date range changes.

fieldProps.onCalendarChange

(dates: [Dayjs | null, Dayjs | null]) => void

Callback when date is selected in calendar (before clicking OK).

fieldProps.minDate

Dayjs

Minimum selectable date.

fieldProps.maxDate

Dayjs

Maximum selectable date.

ProFormDateTimePicker

Date and time picker component.

Import

import { ProFormDateTimePicker } from '@ant-design/pro-components';

Usage

<ProFormDateTimePicker
  name="eventTime"
  label="Event Time"
  fieldProps={{
    format: 'YYYY-MM-DD HH:mm:ss'
  }}
/>

Props

Extends ProFormDatePicker props with showTime={true} by default.

fieldProps.format

string

default:"'YYYY-MM-DD HH:mm:ss'"

Date and time format.

fieldProps.showTime

boolean | TimePickerProps

default:"true"

Time picker configuration:

showTime={{
  format: 'HH:mm',
  minuteStep: 15,
  disabledHours: () => [0, 1, 2, 3, 4, 5]
}}

ProFormTimePicker

Time picker component for selecting time.

Import

import { ProFormTimePicker } from '@ant-design/pro-components';

Usage

Basic
With Seconds
12 Hour Format

<ProFormTimePicker
  name="meetingTime"
  label="Meeting Time"
  fieldProps={{
    format: 'HH:mm'
  }}
/>

<ProFormTimePicker
  name="preciseTime"
  label="Precise Time"
  fieldProps={{
    format: 'HH:mm:ss'
  }}
/>

<ProFormTimePicker
  name="time12h"
  label="Time (12h)"
  fieldProps={{
    format: 'hh:mm A',
    use12Hours: true
  }}
/>

Props

Extends ProFormText props and Ant Design TimePicker props.

fieldProps.format

string

default:"'HH:mm:ss'"

Time format. Common formats:

HH:mm:ss: 14:30:00 (24-hour)
HH:mm: 14:30 (24-hour, no seconds)
hh:mm A: 02:30 PM (12-hour)

fieldProps.use12Hours

boolean

default:"false"

Whether to use 12-hour time format with AM/PM.

fieldProps.hourStep

number

default:"1"

Hour selection interval.

fieldProps.minuteStep

number

default:"1"

Minute selection interval.

fieldProps.secondStep

number

default:"1"

Second selection interval.

fieldProps.disabledTime

() => { disabledHours?: () => number[], disabledMinutes?: (hour: number) => number[], disabledSeconds?: (hour: number, minute: number) => number[] }

Function to disable specific time ranges:

disabledTime={() => ({
  disabledHours: () => [0, 1, 2, 3, 4, 5, 22, 23],
  disabledMinutes: (hour) => hour === 12 ? [0, 30] : [],
})}

fieldProps.hideDisabledOptions

boolean

default:"false"

Whether to hide disabled options in the time selection panel.

fieldProps.showNow

boolean

default:"true"

Whether to show “Now” button.

fieldProps.onChange

(time: Dayjs | null, timeString: string) => void

Callback when selected time changes.

ProFormTimeRangePicker

Time range picker for selecting start and end times.

Import

import { ProFormTimeRangePicker } from '@ant-design/pro-components';

Usage

<ProFormTimeRangePicker
  name="workingHours"
  label="Working Hours"
  fieldProps={{
    format: 'HH:mm'
  }}
  placeholder={['Start time', 'End time']}
/>

Props

Extends ProFormTimePicker props for time range selection.

fieldProps.onChange

(times: [Dayjs | null, Dayjs | null], timeStrings: [string, string]) => void

Callback when time range changes.

Common Features

Show Date Format with Day.js

All date components use Day.js for date manipulation. The value type is Dayjs object:

import dayjs from 'dayjs';

// Set initial value
<ProFormDatePicker
  initialValue={dayjs('2024-03-15')}
/>

// Handle onChange
<ProFormDatePicker
  fieldProps={{
    onChange: (date, dateString) => {
      console.log('Dayjs object:', date);
      console.log('Formatted string:', dateString);
      console.log('Unix timestamp:', date?.unix());
    }
  }}
/>

Show Disable Past/Future Dates

Use disabledDate to control selectable dates:

// Disable past dates
<ProFormDatePicker
  fieldProps={{
    disabledDate: (current) => current && current < dayjs().startOf('day')
  }}
/>

// Disable future dates
<ProFormDatePicker
  fieldProps={{
    disabledDate: (current) => current && current > dayjs().endOf('day')
  }}
/>

// Allow only weekdays
<ProFormDatePicker
  fieldProps={{
    disabledDate: (current) => {
      const day = current.day();
      return day === 0 || day === 6; // Disable Sunday(0) and Saturday(6)
    }
  }}
/>

Show Value Transformation

Transform date values between form and submission formats:

<ProFormDatePicker
  name="birthDate"
  // Convert string to Dayjs when loading form
  convertValue={(value) => value ? dayjs(value) : undefined}
  // Convert Dayjs to string when submitting
  transform={(value) => value ? value.format('YYYY-MM-DD') : undefined}
/>

// For date range
<ProFormDateRangePicker
  name="dateRange"
  transform={(value) => ({
    startDate: value?.[0]?.format('YYYY-MM-DD'),
    endDate: value?.[1]?.format('YYYY-MM-DD')
  })}
/>

Show Read-only Mode

In read-only mode, dates display as formatted text:

<ProFormDatePicker
  readonly
  name="createdAt"
  label="Created At"
/>

<ProFormDateRangePicker
  readonly
  name="period"
  label="Period"
/>

Show Localization

Date components respect the locale setting from ProConfigProvider:

import { ConfigProvider } from 'antd';
import enUS from 'antd/locale/en_US';
import zhCN from 'antd/locale/zh_CN';

<ConfigProvider locale={zhCN}>
  <ProForm>
    <ProFormDatePicker name="date" />
  </ProForm>
</ConfigProvider>

Components API

Form Fields API

Utilities

​ProFormDatePicker

​Import

​Usage

​Props

​ProFormDatePicker.Week

​Import

​Usage

​Props

​ProFormDatePicker.Month

​Import

​Usage

​Props

​ProFormDatePicker.Quarter

​Import

​Usage

​Props

​ProFormDatePicker.Year

​Import

​Usage

​Props

​ProFormDateRangePicker

​Import

​Usage

​Props

​ProFormDateTimePicker

​Import

​Usage

​Props

​ProFormTimePicker

​Import

​Usage

​Props

​ProFormTimeRangePicker

​Import

​Usage

​Props

​Common Features

Build docs developers (and LLMs) love

ProFormDatePicker

Import

Usage

Props

ProFormDatePicker.Week

Import

Usage

Props

ProFormDatePicker.Month

Import

Usage

Props

ProFormDatePicker.Quarter

Import

Usage

Props

ProFormDatePicker.Year

Import

Usage

Props

ProFormDateRangePicker

Import

Usage

Props

ProFormDateTimePicker

Import

Usage

Props

ProFormTimePicker

Import

Usage

Props

ProFormTimeRangePicker

Import

Usage

Props

Common Features