ant-design/docs/react/use-custom-date-library.en-US.md

order	title
7.5	Use custom date library

By default, Ant Design uses Day.js to handle time and date. Day.js is an immutable date-time library alternative to Moment.js with the same API.

You might want to use another date library (Ant design currently supports moment, date-fns, and luxon). We provide two ways to customize:

Custom component

The first way is to use generatePicker (or generateCalendar) to help create Picker components.

First, we initialize an antd demo with create-react-app. You can refer to Use in TypeScript, or you can start directly here init antd

DatePicker.tsx

Create src/components/DatePicker.tsx.

For example:

import generatePicker from 'antd/es/date-picker/generatePicker';
import type { Moment } from 'moment';
import momentGenerateConfig from 'rc-picker/lib/generate/moment';

const DatePicker = generatePicker<Moment>(momentGenerateConfig);

export default DatePicker;

TimePicker.tsx

Create src/components/TimePicker.tsx.

For example:

import type { PickerTimeProps } from 'antd/es/date-picker/generatePicker';
import type { Moment } from 'moment';
import * as React from 'react';
import DatePicker from './DatePicker';

export interface TimePickerProps extends Omit<PickerTimeProps<Moment>, 'picker'> {}

const TimePicker = React.forwardRef<any, TimePickerProps>((props, ref) => (
  <DatePicker {...props} picker="time" mode={undefined} ref={ref} />
));

TimePicker.displayName = 'TimePicker';

export default TimePicker;

Calendar.tsx

Create src/components/Calendar.tsx.

For example:

import generateCalendar from 'antd/es/calendar/generateCalendar';
import type { Moment } from 'moment';
import momentGenerateConfig from 'rc-picker/lib/generate/moment';

const Calendar = generateCalendar<Moment>(momentGenerateConfig);

export default Calendar;

Export Custom component

Create src/components/index.tsx.

For example:

export { default as Calendar } from './Calendar';
export { default as DatePicker } from './DatePicker';
export { default as TimePicker } from './TimePicker';

Use Custom component

Modify src/App.tsx,import moment and custom component.

- import { DatePicker, Calendar } from 'antd';
- import format from 'dayjs';

+ import { DatePicker, TimePicker, Calendar } from './components';
+ import format from 'moment';

antd-moment-webpack-plugin

We also provide another implementation, which we provide with @ant-design/moment-webpack-plugin, replacing Day.js with moment directly without changing a line of existing code. More info can be found at @ant-design/moment-webpack-plugin.

// webpack-config.js
const AntdMomentWebpackPlugin = require('@ant-design/moment-webpack-plugin');

module.exports = {
  // ...
  plugins: [new AntdMomentWebpackPlugin()],
};

Use date-fns

date-fns currently supports custom component methods similar to dayjs. The difference is that the parameter types used are different. Support is provided in antd 4.5.0 and above.

For Example:

DatePicker.tsx

Create src/components/DatePicker.tsx.

Code as follows:

import generatePicker from 'antd/es/date-picker/generatePicker';
import 'antd/es/date-picker/style/index';
import dateFnsGenerateConfig from 'rc-picker/lib/generate/dateFns';

const DatePicker = generatePicker<Date>(dateFnsGenerateConfig);

export default DatePicker;

Use luxon

Since antd 5.4.0, luxon can be used instead of dayjs and supports the same functionality, but it does introduce some differences in behavior that we will explain below.

Implementation

Create a src/components/DatePicker.tsx file, and implement the luxon based picker as follows:

import generatePicker from 'antd/es/date-picker/generatePicker';
import 'antd/es/date-picker/style/index';
import type { DateTime } from 'luxon';
import luxonGenerateConfig from 'rc-picker/lib/generate/luxon';

const DatePicker = generatePicker<DateTime>(luxonGenerateConfig);

export default DatePicker;

Notable differences with day-js

luxon users should be familiar with the fact that it does not come with a custom implementation for localization. Instead, it relies on the browser's native Intl API.

This introduces some formatting differences with the other date libraries. As of today, the main differences are:

• First day of the week is always Monday regardless of locale.
• Week of year number is sometimes different (ISO week rules are used to determine it).
• Short week days format will sometimes be different for custom locales (it might have 3 characters instead of 2).
• Selected week label format will be slightly different (e.g. "2021-01" instead of "2021-1st").

It is possible to customize these default luxon behaviors by adjusting the luxon config:

import generatePicker from 'antd/es/date-picker/generatePicker';
import 'antd/es/date-picker/style/index';
import type { DateTime } from 'luxon';
import luxonGenerateConfig from 'rc-picker/lib/generate/luxon';

const customLuxonConfig = {
  ...luxonGenerateConfig,
  getWeekFirstDay: (locale) => {
    // Your custom implementation goes here
  },
};

const DatePicker = generatePicker<DateTime>(customLuxonConfig);

export default DatePicker;

Note that by doing such customization, the resulting DatePicker behavior might be altered in unexpected ways, so make sure you are testing for edge cases.