DatePicker

To select or input a date.
Import
Source components/date-picker
Docs Edit this page

When To Use#

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

Examples#






Basic

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

      Loading...
Date
Switchable picker

Switch in different types of pickers by Select.

      Loading...






Three Sizes

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

      Loading...


Disabled

A disabled state of the DatePicker.

      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().
      Loading...
Variants

Variants of DatePicker, there are four variants: outlinedfilledborderless and underlined.

      Loading...
20.0.0
Status

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

      Loading...



Week Number

Display week numbers with nzShowWeekNumber.

      Loading...





Range Picker

Set range picker type by nzMode prop.

      Loading...



Date Format

We can set the date format by nzFormat.

      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.

      Loading...




Disabled Date & Time

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

      Loading...

Presetted Ranges

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

      Loading...

Customized Date Rendering

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

      Loading...
Su Mo Tu We Th Fr Sa
28
29
30
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
Today
Inline mode

We can set the inline mode by nzInline.

      Loading...



Placement

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

      Loading...

API#

Note: Some of nz-date-picker's locale are coming from Angular i18n, that should be provided in the file app.config.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 ConfigVersion
[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 dateDate | Date[]--
[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 inputstring | string[]-
[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 iconstring | TemplateRef-✅
[nzBorderless]remove the borderbooleanfalse-
[nzVariant]Variants of DatePicker'outlined' | 'borderless' | 'filled' | 'underlined''outlined'✅20.0.0
[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.

Q: The overlay layer element does not follow the scroll position when scrolling#

By default, the overlay layer element uses body as the scroll container. If using another scroll container, add the CdkScrollable directive to the custom scroll container element. Note: You need to import the CdkScrollable directive or ScrollingModule module from @angular/cdk/scrolling.