How to Customize DatePicker and TimePicker in Ant Design: Formats, Ranges, and Advanced Options

You can customize Ant Design's DatePicker and TimePicker components using the format prop, which accepts simple strings, arrays of patterns, custom functions, or mask objects for strict input validation.

The ant-design/ant-design repository implements these components through a sophisticated picker engine that supports extensive customization of date formats, time displays, and range selections. Whether you need to support multiple input formats, enforce strict masking, or create custom display functions, the underlying architecture in components/date-picker/generatePicker/ provides the necessary flexibility.

Core Architecture of Ant Design Pickers

Ant Design's picker components are built on top of the @rc-component/picker engine. The public API definitions reside in components/date-picker/generatePicker/interface.ts, while the concrete component implementations are generated by components/date-picker/generatePicker/generateSinglePicker.tsx and exported through components/date-picker/index.tsx.

Layer	File Path	Responsibility
Prop Types	components/date-picker/generatePicker/interface.ts	Defines PickerProps, RangePickerProps, and the format prop type definitions.
Component Generator	components/date-picker/generatePicker/generateSinglePicker.tsx	Factory function that creates DatePicker, WeekPicker, MonthPicker, QuarterPicker, YearPicker, and TimePicker components.
Export Entry	components/date-picker/index.tsx	Calls generatePicker with Dayjs configuration and re-exports all generated components.
TimePicker Wrapper	components/time-picker/index.tsx	Re-exports the same internal picker with picker="time" preset and TimePicker-specific type definitions.

Customizing Date and Time Formats

The format prop in PickerProps (defined in generatePicker/interface.ts) accepts four distinct shapes, providing flexibility for different localization and validation requirements.

String Formats

The simplest approach uses a Dayjs-compatible format string. This is passed directly to the underlying RCPicker component in generateSinglePicker.tsx (lines 199-210).

import { DatePicker } from 'antd';
import dayjs from 'dayjs';

<DatePicker
  defaultValue={dayjs('2024/01/15', 'YYYY/MM/DD')}
  format="YYYY/MM/DD"
/>

Multiple Input Formats

Supply an array of strings to allow users to type dates in various patterns. The picker attempts to parse the input against each format in order, using the first successful match.

import { DatePicker } from 'antd';
import dayjs from 'dayjs';

const acceptedFormats = ['DD/MM/YYYY', 'DD-MM-YYYY', 'YYYY/MM/DD'];

<DatePicker
  defaultValue={dayjs('15/01/2024', acceptedFormats[0])}
  format={acceptedFormats}
/>

Custom Formatter Functions

For complete control over display, provide a function that receives a Dayjs instance and returns a formatted string. This is useful for adding prefixes, suffixes, or custom localization.

import { DatePicker } from 'antd';
import dayjs from 'dayjs';

const customFormat = (value: dayjs.Dayjs) => 
  `🚀 ${value.format('MMM D, YYYY')}`;

<DatePicker
  defaultValue={dayjs()}
  format={customFormat}
/>

Input Masking (v5+)

Ant Design v5 introduced mask objects that enforce strict input patterns as users type. This prevents invalid date entry by restricting keyboard input to the defined format pattern.

import { DatePicker } from 'antd';

<DatePicker
  format={{ format: 'YYYY-MM-DD', type: 'mask' }}
/>

Working with Range Selection

The RangePicker component is exported as DatePicker.RangePicker from components/date-picker/index.tsx. It inherits all PickerProps while adding range-specific callbacks like onCalendarChange and onOk.

import { DatePicker } from 'antd';
import dayjs from 'dayjs';

const { RangePicker } = DatePicker;

<RangePicker
  defaultValue={[
    dayjs('2024-01-01', 'YYYY-MM-DD'),
    dayjs('2024-01-31', 'YYYY-MM-DD')
  ]}
  format="YYYY-MM-DD"
  onCalendarChange={(dates, dateStrings) => {
    console.log('Selected range:', dateStrings);
  }}
/>

TimePicker Specific Customizations

The TimePicker component (defined in components/time-picker/index.tsx) is generated by the same factory function but with picker="time" preset. While DatePicker uses the showTime prop to enable time selection alongside dates, TimePicker uses the format prop directly to control time display.

import { TimePicker } from 'antd';
import dayjs from 'dayjs';

<TimePicker
  defaultValue={dayjs('12:34', 'HH:mm')}
  format="HH:mm:ss"
/>

When using DatePicker with time support, configure the time format through the showTime object:

import { DatePicker } from 'antd';
import dayjs from 'dayjs';

<DatePicker
  defaultValue={dayjs('2024-01-15 08:30', 'YYYY-MM-DD HH:mm')}
  format="YYYY-MM-DD HH:mm"
  showTime={{ format: 'HH:mm' }}
/>

Summary

• Format flexibility: The format prop accepts strings, arrays, functions, or mask objects to control display and input validation.
• Architecture: Components are generated by generateSinglePicker.tsx based on types defined in generatePicker/interface.ts, then exported through date-picker/index.tsx and time-picker/index.tsx.
• Range selection: Use DatePicker.RangePicker for date ranges, which supports the same format options plus range-specific callbacks.
• Time handling: TimePicker uses format directly, while DatePicker uses showTime to enable time selection alongside dates.
• Input masking: Ant Design v5 supports mask objects to enforce strict input patterns as users type.

Frequently Asked Questions

How do I allow users to type dates in multiple formats?

Pass an array of format strings to the format prop. The picker will attempt to parse user input against each format in the array order, using the first successful match. For example: format={['DD/MM/YYYY', 'YYYY-MM-DD']}.

What is the difference between DatePicker with showTime and the TimePicker component?

DatePicker with showTime displays a calendar panel with an integrated time selector, allowing users to pick both date and time in one component. The TimePicker component (which uses picker="time" internally) displays only a time selection interface without the calendar panel. Both accept the format prop, but DatePicker configures time display through the showTime object while TimePicker uses format directly.

How does input masking work in Ant Design v5?

Input masking enforces strict format compliance as users type. Instead of a string, pass an object to the format prop: format={{ format: 'YYYY-MM-DD', type: 'mask' }}. This prevents users from entering invalid characters or exceeding format lengths, ensuring the input always matches the specified pattern.

Can I use a custom function to format the displayed date?

Yes, the format prop accepts a function that receives a Dayjs instance (or Date) and returns a string. This is useful for adding prefixes, custom localization, or non-standard formatting. For example: format={(value) => \Q${value.quarter()} ${value.year()}`}`.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}