--- title: DatePicker path: component/date-picker group: Data Entry --- ## DatePicker DateTime pickers, provides basic time choosing functionality. ### Guides - Included pickers：`DatePicker`,`WeekPicker`,`MonthPicker`,`QuarterPicker`,`YearPicker`,`DateRangePicker`,`CombinedDateRangePicker`,`TimePicker`,`TimeRangePicker` , `CombinedTimeRangePicker` ,`SingleCalendarDatePanelPicker` and `CombinedPanelRangePicker` - `DatePicker` ,`CombinedDateRangePicker` , `DateRangePicker` , `SingleCalendarDatePanelPicker` and `CombinedPanelRangePicker` can use `showTime` to allow time selection. ### API #### Common API | Property | Description | Type | Default | Required | | ------------ | ------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------- | -------- | | value | Selected date | - | - | Yes | | onChange | Callback when the selected time is changing | - | - | Yes | | valueType | Set `onChange`'s value type, options:`'string'` \| `'number'` \| `'date'` | `string` | `'string'` | No | | format | Format string date | `string` | Different pickers have different values | No | | disabledDate | Specify the date that cannot be selected | `(date: Date) => {}` \| `IDisableDateMap` | - | No | | defaultDate | Default date value | `string` \| `Date` \| `number` | `new Date()` | No | | disabled | Determine whether the DatePicker is disabled | `boolean` | `false` | No | | canClear | Whether the date can be cleared | `boolean` | `true` | No | | openPanel | The open state of picker | `boolean` | `false` | No | | onOpen | Callback when the popup is popped up | `function` | - | No | | onClose | Callback when the popup is closed | `function` | - | No | | width | To set the width of input | `string` \| `number` | - | No | | className | Cusotm className | `string` | `''` | No | ```ts interface IDisableDateMap { min?: string | Date | number; // The minimium selectable date max?: string | Date | number; // The maximum selectable date } ``` #### DatePicker API | Property | Description | Type | Default | Required | | ------------ | ------------------------------------------- | ---------------------------------------- | ------------------------ | -------- | | value | Selected date | `string` \| `Date` \| `number` | - | Yes | | onChange | Callback when the selected date is changing | `(date: string | Date | number) => {}` | - | Yes | | placeholder | The placeholder of date input | `string` | `'Please select a date'` | No | | format | To set the date format | `string` | `'YYYY-MM-DD'` | No | | hideFooter | Whether to show footer | `boolean` | `false` | No | | showTime | To provide an additional time selection | `boolean` \| `object` | `false` | No | | disabledTime | To specify the time that cannot be selected | `(date?: Date) => IDisabledTimeOption` | - | No | | showLunarDate | Whether to display lunar date | `boolean` | `false` | No | | lunarValueFormatter | Format lunar date backfill value | `(date: Date) => string` | - | No | **Additional** - When return value of `showTime` is an object, to provide an additional time selection, there are some properties within this object: `format`、`hourStep`、`minuteStep`、`secondStep`, but redefines the type of `defaultTime` to be `string | (date: Date) => string` - `disabledTime` only works with `showTime`, see the details in `TimePicker` - `format` should be `'YYYY-MM-DD HH:mm:ss'` when `showTime` is `true` - `lunarValueFormatter` only works with `showLunarDate` #### WeekPicker API | Property | Description | Type | Default | Required | | ------------ | ------------------------------------------- | ----------------------------------------------- | ------------------------ | -------- | | value | Selected date | `Array` | - | Yes | | onChange | Callback when the selected date is changing | `(date: Array) => {}` | - | Yes | | placeholder | The placeholder of date input | `string` | `'Please select a week'` | No | | weekStartsOn | To set the start day of a week | `WeekStartsOnMap` | `WeekStartsOnMap.Monday` | No | | format | To set the date format | `string` | `'YYYY-MM-DD'` | No | | hideFooter | Whether to show footer | `boolean` | `false` | No | **Additional** - `value` is a range of dates in `WeekPicker` - `weekStartsOnMap`: `Monday`、`Tuesday`、`Wednesday`、`Thursday`、`Friday`、`Saturday`、`Sunday` #### YearPicker / MonthPicker API | Property | Description | Type | Default | Required | | ----------- | ------------------------------------------- | ---------------------------------------- | ----------------------------------------------------- | -------- | | value | Selected date | `string` \| `Date` \| `number` | - | Yes | | onChange | Callback when the selected date is changing | `(date: string | Date | number) => {}` | - | Yes | | placeholder | The placeholder of date input | string | `'Please select a year'` \| `'Please select a month'` | No | | format | To set the date format | string | `'YYYY'` \| `'YYYY-MM'` | No | **Additional** - `value` is a single date in `YearPicker` / `MonthPicker` #### QuarterPicker API | Property | Description | Type | Default | Required | | ----------- | ------------------------------------------- | ----------------------------------------------- | --------------------------- | -------- | | value | Selected date | `Array` | - | Yes | | onChange | Callback when the selected date is changing | `(date: Array) => {}` | - | Yes | | placeholder | The placeholder of date input | `string` | `'Please select a quarter'` | No | | format | To set the date format | `string` | `'YYYY-MM'` | No | **Additional** - `value` is a single date in `QuarterPicker` #### TimePicker API | Property | Description | Type | Default | Required | | ------------ | ------------------------------------------- | --------------------------- | ------------------------ | -------- | | value | Selected time | `string` | - | Yes | | onChange | Callback when the selected time is changing | `(date: string ) => {}` | - | Yes | | defaultTime | To set default time | `string` | - | No | | placeholder | The placeholder of time input | `string` | `'Please select a time'` | No | | format | To set the time format | `string` | `'HH:mm:ss'` | No | | disabledTime | To specify the time that cannot be selected | `() => IDisabledTimeOption` | - | No | | hourStep | Interval between hours in picker | `number` | `1` | No | | minuteStep | Interval between minutes in picker | `number` | `1` | No | | secondStep | Interval between seconds in picker | `number` | `1` | No | ```ts interface IDisabledTimeOption { disabledHours?: () => number[]; disabledMinutes: (hour: number) => number[]; disabledSeconds?: (hour: number, minute: number) => number[]; } ``` ### SingleCalendarDatePanelPicker API | Property | Description | Type | Default | Required | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ------- | -------- | | selected | Selected date | `Date\|null` | - | 是 | | onSelected | Callback when the selected date is changing | `(date: Date ) => {}` | - | 是 | | defaultPanelDate | The default Date of panel | `Date` | - | 否 | | disabledPanelDate | The disabled Date | `(date:Date) => boolean` | - | 是 | | onChangePanel | The callback function of the type of switch panel | `(type:IPickerType) => {}` | - | 否 | | onPanelDateChange | Callback function for the value of the toggle panel | `(date:Date) => {}` | - | 否 | | hideFooter | Should hide the footer of panel | `boolean` | `false` | 否 | | showTime | To provide an additional time | `boolean` \| `object` | `false` | 否 | | disabledTime | To specify the time that cannot be selected | `(date?: Date) => IDisabledTimeOption` | - | 否 | | popText | The content when selected a date cell | `string` | - | 否 | | footerText | The content on the footer to dump to now | `string` | - | 否 | | combinedLeft | Whether it is the left calendar of the combined calendar panel, if yes, hide the next month/year icon at the top right of this component | `boolean` | false | 否 | | combinedRight | Whether it is the right calendar of the combined calendar panel, if yes, hide the next month/year icon at the top left of this component | `boolean` | false | 否 | | hoverRangeDate | The date range for hover | `[Date,Date]\|null` | - | 否 | | rangeDate | The date range has been selected | `[Date,Date]\|null` | - | 否 | #### DateRangePicker / CombinedDateRangePicker （Base on DatePicker） | Property | Description | Type | Default | Required | | ----------- | ------------------------------------------------- | ----------------------------------------------- | --------------------------- | -------- | | value | Selected date range | `Array` | - | Yes | | onChange | Callback when the selected date range is changing | `(date: Array) => {}` | - | Yes | | placeholder | The placeholder of dates input | `[string, string]` | `['Start date','End date']` | No | | defaultDate | Default date range | `[string, string]` | - | No | | dateSpan | Quick set the time span | `number` | - | No | **Additional** - When return value of `showTime` is an object, `defaultTime` should be `[string | (date: Date) => string, string | (date: Date) => string]`. (default: ['00:00:00','23:59:59']) - `disabledDate(val, type)` or `disabledTime(val, type)`, the `type` is `'start' | 'end'` - Only supports `dateSpan` for `DateRangePicker` and `CombinedDateRangePicker`. - Definition of `disabled` and `canClear` is `boolean | boolean[]` in `DateRangePicker`. ### CombinedPanelRangePicker （基于 DateRangePicker 和 TimePicker ） | Property | Description | Type | Default | Required | | --------------- | ------------------------------------------------------------------------- | ---------------------------------------------- | -------------- | -------- | | value | Selected date range | `Array\| null` | - | Yes | | onChange | Callback when the selected date range is changing | `(date: Array) => {}` | - | Yes | | defaultDate | Default date value | `[string, string]` | - | No | | dateSpan | Quick set the time span | `number` | - | No | | valueType | Set `onChange`'s value type, options:`'string'` \| `'number'` \| `'date'` | `string` | `'string'` | No | | format | Format string | `string` | `'YYYY-MM-DD'` | No | | disabledDate | Specify the date that cannot be selected | `(date: Date) => {}` \| `IDisableDateMap` | - | No | | showTime | To provide an additional time selection | `boolean` \| `object` | `false` | No | | hideConfirm | hide confirm button in additional time selection | `boolean` | `false` | No | | className | the class of this component | `string` | - | No | | leftClassName | the class of the left calendar | `string` | - | No | | rightClassName | the class of the right calendar | `string` | - | No | | footerClassName | the class of the additional time selection | `string` | - | No | **Additional** - When return value of `showTime` is an object, `defaultTime` should be `[string | (date: Date) => string, string | (date: Date) => string]`. (default: ['00:00:00','23:59:59']) - `disabledDate(val, type)` or `disabledTime(val, type)`, the `type` is `'start' | 'end'` #### TimeRangePicker / CombinedTimeRangePicker API （Base on TimePicker） | Property | Description | Type | Default | Required | | ----------- | ------------------------------------------- | --------------------------------- | --------------------------- | -------- | | value | Selected time | `[string, string]` | - | Yes | | onChange | Callback when the selected time is changing | `(date: [string, string] ) => {}` | - | Yes | | defaultTime | To set default time | `[string, string]` | - | No | | placeholder | The placeholder of time input | `[string, string]` | `['Start time','End time']` | No | **Additional** - `disabledTime(val, type)`, the `type` is `'start' | 'end'` #### Functions - Provide some useful functions: e.g. `disabledTimeWithRange`、`getDisabledDateAndTimeWithRangeProps`, that can use in your `disabledTime` handlers. You need to manually import them from `zent/es/date-picker/disabledHelpers`. #### Format string | | Format character | Output | | --------- | ---------------- | ---------------------------------------- | | **Year** | YY | 70 71 ... 29 30 | | | YYYY | 1970 1971 ... 2029 2030 | | **Month** | M | 1 2 ... 11 1 | | | MM | 01 02 ... 11 12 | | | MMM | Jan, Feb ... Nov, Dec | | | MMMM | January, February ... November, December | | **Date** | D | 1 2 ... 30 31 | | | DD | 01 02 ... 30 31 | | | d | 0 1 ... 5 6 | | | ddd | Sun, Mon ... Fri, Sat | | | dddd | Sunday, Monday ... Friday, Saturday |