DatePicker

To select or input a date.

When To Use#

By clicking the input box, you can select a date from a popup calendar.

import { NzDatePickerModule } from 'ng-zorro-antd/date-picker';

Examples






Basic

Basic use case. Users can select or input a date in panel.

expand codeexpand code
      Loading...
Date
Switchable picker

Switch in different types of pickers by Select.

expand codeexpand code
      Loading...






Three Sizes

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

expand codeexpand code
      Loading...


Disabled

A disabled state of the DatePicker.

expand codeexpand code
      Loading...
Customized Range Picker

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

  • Use the nzDisabledDate property to limit the start and end dates.
  • Improve user experience with open().
expand codeexpand code
      Loading...

Bordered-less

Bordered-less style component.

expand codeexpand code
      Loading...
Status

Add status to DatePicker with nzStatus, which could be error or warning.

expand codeexpand code
      Loading...



Week Number

Display week numbers with nzShowWeekNumber.

expand codeexpand code
      Loading...





Range Picker

Set range picker type by nzMode prop.

expand codeexpand code
      Loading...



Date Format

We can set the date format by nzFormat.

expand codeexpand code
      Loading...

Choose Time

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

expand codeexpand code
      Loading...




Disabled Date & Time

Disabled part of dates and time by nzDisabledDate and nzDisabledTime respectively.

expand codeexpand code
      Loading...

Presetted Ranges

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

expand codeexpand code
      Loading...

Customized Date Rendering

We can customize the rendering of date cells in the calendar by providing a nzDateRender function to DatePicker.

expand codeexpand code
      Loading...
Su Mo Tu We Th Fr Sa
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
1
2
3
4
5
6
7
8
9
10
11
Today
Inline mode

We can set the inline mode by nzInline.

expand codeexpand code
      Loading...



Placement

You can manually specify the position of the popup via nzPlacement.

expand codeexpand code
      Loading...

API#

Note: Some of nz-date-picker's locale are coming from Angular i18n, that should be provided in the file of app.module.ts.

For example:

import { registerLocaleData } from '@angular/common';
import en from '@angular/common/locales/en';

registerLocaleData(en);

Note: All input and output date objects are Date, you can manipulate it with date-fns.

Common API#

The following APIs are shared by nz-date-picker, nz-range-picker.

PropertyDescriptionTypeDefaultGlobal Config
[nzId]input id attribute inside the componentstring-
[nzAllowClear]Whether to show clear buttonbooleantrue-
[nzAutoFocus]get focus when component mountedbooleanfalse-
[nzBackdrop]whether or not the overlay should attach a backdropbooleanfalse
[nzDefaultPickerValue]default picker dateDateDate[]-
[nzDisabled]determine whether the nz-date-picker is disabledbooleanfalse-
[nzDisabledDate]specify the date that cannot be selected(current: Date) => boolean--
[nzDropdownClassName]to customize the className of the popup calendarstring--
[nzFormat]to set the date format, see nzFormat special instructionsstring-
[nzInputReadOnly]set the readonly attribute of the input tag (avoids virtual keyboard on touch devices)booleanfalse-
[nzLocale]localization configurationobjectdefault-
[nzMode]Set picker mode'date' | 'week' | 'month' | 'quarter' | 'year''date'
[nzPlaceHolder]placeholder of date inputstringstring[]-
[nzPopupStyle]to customize the style of the popup calendarobject{}-
[nzRenderExtraFooter]render extra footer in panelTemplateRef | string | (() => TemplateRef | string)-
[nzSize]determine the size of the input box, the height of large and small, are 40px and 24px respectively, while default size is 32px'large' | 'small'--
[nzStatus]Set validation status'error' | 'warning'-
[nzPlacement]The position where the selection box pops up'bottomLeft' | 'bottomRight' | 'topLeft' | 'topRight''bottomLeft'
[nzSuffixIcon]the custom suffix iconstringTemplateRef-
[nzBorderless]remove the borderbooleanfalse-
[nzInline]inline modebooleanfalse-
(nzOnOpenChange)a callback emitter, can be executed whether the popup calendar is popped up or closedEventEmitter<boolean>--
(nzOnPanelChange)a callback emitter, can be executed when the panel changesEventEmitter<NzPanelChangeType>--

Common Methods#

NameDescription
open()open calendar panel
close()close calendar panel

nz-date-picker#

PropertyDescriptionTypeDefault
[(ngModel)]DateDate-

nz-date-picker[nzMode="date"]#

PropertyDescriptionTypeDefault
[nzDateRender]custom rendering function for date cells (Not support by month-picker/year-picker)-TemplateRef<Date> | string | ((d: Date) => TemplateRef<Date> | string)
[nzDisabledTime]to specify the time that cannot be selected(current: Date) => { nzDisabledHours, nzDisabledMinutes, nzDisabledSeconds }-
[nzShowTime]to provide an additional time selectionobject | booleanTimePicker Options
[nzShowToday]whether to show 'Today' buttonbooleantrue
[nzShowNow]whether to show 'Now' button on panel when nzShowTime is setbooleantrue
[nzShowWeekNumber]whether to show the week number on each row (Only supported by date picker. Week picker always shows week numbers)booleanfalse
(nzOnOk)callback when click ok buttonEventEmitter<Date>-

nz-range-picker#

PropertyDescriptionTypeDefault
[(ngModel)]DateDate[]-
[nzRanges]preseted ranges for quick selection{ [ key: string ]: Date[] } | { [ key: string ]: () => Date[] }-
[nzSeparator]separatorstring | TemplateRef'~'
(nzOnCalendarChange)The start time or the end time of the range change callbackEventEmitter<Date[]>-

nz-range-picker[nzMode="date"]#

PropertyDescriptionTypeDefault
[nzShowTime]to provide an additional time selectionobject | booleanTimePicker Options
[nzDisabledTime]to specify the time that cannot be selected(current: Date, partial: 'start' | 'end') => { nzDisabledHours, nzDisabledMinutes, nzDisabledSeconds }-
[nzShowWeekNumber]whether to show the week number on each row (Only supported by date picker. Week picker always shows week numbers)booleanfalse
(nzOnOk)click ok callbackEventEmitter<Date[]>-

Currently, supported nz-time-picker parameters in nzShowTime are: nzFormat, nzHourStep, nzMinuteStep, nzSecondStep, nzDisabledHours, nzDisabledMinutes, nzDisabledSeconds, nzHideDisabledOptions, nzDefaultOpenValue, nzAddOn

FAQ#

Why does manual input not take effect after setting nzFormat="dd/MM/yyyy"#

You need to use date-fns. Date formatting currently supports two methods: DatePipe ( default, syntax reference) and date-fns ( see How to format a date using date-fns).NG-ZORRO takes the function provided by date-fns to implement date deserialization after using it.