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 this Component Individually#

You can get more detail here.

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

Examples




~

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

expand codeexpand code
import { Component } from '@angular/core';
import getISOWeek from 'date-fns/get_iso_week';
import { en_US, zh_CN, NzI18nService } from 'ng-zorro-antd/i18n';

@Component({
  selector: 'nz-demo-date-picker-basic',
  template: `
    <nz-date-picker [(ngModel)]="date" (ngModelChange)="onChange($event)"></nz-date-picker>
    <br />
    <nz-month-picker
      [(ngModel)]="date"
      (ngModelChange)="onChange($event)"
      nzPlaceHolder="Select month"
    ></nz-month-picker>
    <br />
    <nz-year-picker [(ngModel)]="date" (ngModelChange)="onChange($event)" nzPlaceHolder="Select year"></nz-year-picker>
    <br />
    <nz-range-picker [(ngModel)]="dateRange" (ngModelChange)="onChange($event)"></nz-range-picker>
    <br />
    <nz-week-picker [(ngModel)]="date" (ngModelChange)="getWeek($event)" nzPlaceHolder="Select week"></nz-week-picker>
    <br />
    <button nz-button nzType="default" (click)="changeLanguage()">Switch language for all pickers</button>
  `,
  styles: [
    `
      nz-date-picker,
      nz-month-picker,
      nz-year-picker,
      nz-range-picker,
      nz-week-picker {
        margin: 0 8px 12px 0;
      }
    `
  ]
})
export class NzDemoDatePickerBasicComponent {
  date = null;
  dateRange = [];
  isEnglish = false;

  constructor(private i18n: NzI18nService) {}

  onChange(result: Date): void {
    console.log('onChange: ', result);
  }

  getWeek(result: Date): void {
    console.log('week: ', getISOWeek(result));
  }

  changeLanguage(): void {
    this.i18n.setLocale(this.isEnglish ? zh_CN : en_US);
    this.isEnglish = !this.isEnglish;
  }
}




~

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

expand codeexpand code
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-date-picker-size',
  template: `
    <nz-radio-group [(ngModel)]="size">
      <label nz-radio-button nzValue="large">large</label>
      <label nz-radio-button nzValue="default">default</label>
      <label nz-radio-button nzValue="small">small</label>
    </nz-radio-group>
    <br /><br />
    <nz-date-picker [nzSize]="size"></nz-date-picker>
    <br />
    <nz-month-picker [nzSize]="size" nzPlaceHolder="Select Month"></nz-month-picker>
    <br />
    <nz-range-picker [nzSize]="size"></nz-range-picker>
    <br />
    <nz-week-picker [nzSize]="size" nzPlaceHolder="Select Week"></nz-week-picker>
  `,
  styles: [
    `
      nz-date-picker,
      nz-month-picker,
      nz-range-picker,
      nz-week-picker {
        margin: 0 8px 12px 0;
      }
    `
  ]
})
export class NzDemoDatePickerSizeComponent {
  size = 'default';
}


~

A disabled state of the DatePicker.

expand codeexpand code
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-date-picker-disabled',
  template: `
    <nz-date-picker nzDisabled></nz-date-picker>
    <br />
    <nz-month-picker nzDisabled></nz-month-picker>
    <br />
    <nz-range-picker nzDisabled></nz-range-picker>
  `,
  styles: [
    `
      nz-date-picker,
      nz-month-picker,
      nz-range-picker,
      nz-week-picker {
        margin: 0 8px 12px 0;
      }
    `
  ]
})
export class NzDemoDatePickerDisabledComponent {}

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 nzOpen and nzOnOpenChange.
expand codeexpand code
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-date-picker-start-end',
  template: `
    <nz-date-picker
      [nzDisabledDate]="disabledStartDate"
      nzShowTime
      nzFormat="yyyy-MM-dd HH:mm:ss"
      [(ngModel)]="startValue"
      nzPlaceHolder="Start"
      (ngModelChange)="onStartChange($event)"
      (nzOnOpenChange)="handleStartOpenChange($event)"
    >
    </nz-date-picker>
    <nz-date-picker
      [nzDisabledDate]="disabledEndDate"
      nzShowTime
      nzFormat="yyyy-MM-dd HH:mm:ss"
      [(ngModel)]="endValue"
      nzPlaceHolder="End"
      [nzOpen]="endOpen"
      (ngModelChange)="onEndChange($event)"
      (nzOnOpenChange)="handleEndOpenChange($event)"
    >
    </nz-date-picker>
  `,
  styles: [
    `
      nz-date-picker {
        margin: 0 8px 12px 0;
      }
    `
  ]
})
export class NzDemoDatePickerStartEndComponent {
  startValue: Date | null = null;
  endValue: Date | null = null;
  endOpen = false;

  disabledStartDate = (startValue: Date): boolean => {
    if (!startValue || !this.endValue) {
      return false;
    }
    return startValue.getTime() > this.endValue.getTime();
  };

  disabledEndDate = (endValue: Date): boolean => {
    if (!endValue || !this.startValue) {
      return false;
    }
    return endValue.getTime() <= this.startValue.getTime();
  };

  onStartChange(date: Date): void {
    this.startValue = date;
  }

  onEndChange(date: Date): void {
    this.endValue = date;
  }

  handleStartOpenChange(open: boolean): void {
    if (!open) {
      this.endOpen = true;
    }
    console.log('handleStartOpenChange', open, this.endOpen);
  }

  handleEndOpenChange(open: boolean): void {
    console.log(open);
    this.endOpen = open;
  }
}
~

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

expand codeexpand code
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-date-picker-date-render',
  template: `
    <nz-date-picker [nzDateRender]="tplRender"></nz-date-picker>
    <nz-range-picker [nzDateRender]="tplRender"></nz-range-picker>

    <ng-template #tplRender let-current>
      <div class="ant-calendar-date" [class.border]="current.getDate() === 1">
        {{ current.getDate() }}
      </div>
    </ng-template>
  `,
  styles: [
    `
      nz-date-picker,
      nz-month-picker,
      nz-range-picker,
      nz-week-picker {
        margin: 0 8px 12px 0;
      }
      .border {
        border: 1px solid #1890ff;
        border-radius: 50%;
      }
    `
  ]
})
export class NzDemoDatePickerDateRenderComponent {}


~

We can set the date format by nzFormat.

expand codeexpand code
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-date-picker-format',
  template: `
    <nz-date-picker [nzFormat]="dateFormat"></nz-date-picker>
    <br />
    <nz-month-picker [nzFormat]="monthFormat"></nz-month-picker>
    <br />
    <nz-range-picker [nzFormat]="dateFormat"></nz-range-picker>
  `,
  styles: [
    `
      nz-date-picker,
      nz-month-picker,
      nz-range-picker,
      nz-week-picker {
        margin: 0 8px 12px 0;
      }
    `
  ]
})
export class NzDemoDatePickerFormatComponent {
  dateFormat = 'yyyy/MM/dd';
  monthFormat = 'yyyy/MM';
}

~

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
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-date-picker-time',
  template: `
    <nz-date-picker
      nzShowTime
      nzFormat="yyyy-MM-dd HH:mm:ss"
      nzPlaceHolder="Select Time"
      ngModel
      (ngModelChange)="onChange($event)"
      (nzOnOk)="onOk($event)"
    ></nz-date-picker>
    <br />
    <nz-range-picker
      [nzShowTime]="{ nzFormat: 'HH:mm' }"
      nzFormat="yyyy-MM-dd HH:mm"
      [nzPlaceHolder]="['Start Time', 'End Time']"
      ngModel
      (ngModelChange)="onChange($event)"
      (nzOnOk)="onOk($event)"
    ></nz-range-picker>
  `,
  styles: [
    `
      nz-date-picker,
      nz-month-picker,
      nz-range-picker,
      nz-week-picker {
        margin: 0 8px 12px 0;
      }
    `
  ]
})
export class NzDemoDatePickerTimeComponent {
  onChange(result: Date): void {
    console.log('Selected Time: ', result);
  }

  onOk(result: Date): void {
    console.log('onOk', result);
  }
}



~

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

expand codeexpand code
import { Component } from '@angular/core';
import differenceInCalendarDays from 'date-fns/difference_in_calendar_days';
import setHours from 'date-fns/set_hours';
import { DisabledTimeFn, DisabledTimePartial } from 'ng-zorro-antd/date-picker/standard-types';

@Component({
  selector: 'nz-demo-date-picker-disabled-date',
  template: `
    <nz-date-picker
      nzFormat="yyyy-MM-dd HH:mm:ss"
      [nzDisabledDate]="disabledDate"
      [nzDisabledTime]="disabledDateTime"
      [nzShowTime]="{ nzDefaultOpenValue: timeDefaultValue }"
    >
    </nz-date-picker>
    <br />
    <nz-month-picker [nzDisabledDate]="disabledDate" nzPlaceHolder="Select month"></nz-month-picker>
    <br />
    <nz-year-picker [nzDisabledDate]="disabledDate"></nz-year-picker>
    <br />
    <nz-range-picker
      [nzDisabledDate]="disabledDate"
      [nzDisabledTime]="disabledRangeTime"
      [nzShowTime]="{ nzHideDisabledOptions: true, nzDefaultOpenValue: timeDefaultValue }"
      nzFormat="yyyy-MM-dd HH:mm:ss"
    ></nz-range-picker>
  `,
  styles: [
    `
      nz-date-picker,
      nz-month-picker,
      nz-year-picker,
      nz-range-picker,
      nz-week-picker {
        margin: 0 8px 12px 0;
      }
    `
  ]
})
export class NzDemoDatePickerDisabledDateComponent {
  today = new Date();
  timeDefaultValue = setHours(new Date(), 0);

  range(start: number, end: number): number[] {
    const result: number[] = [];
    for (let i = start; i < end; i++) {
      result.push(i);
    }
    return result;
  }

  disabledDate = (current: Date): boolean => {
    // Can not select days before today and today
    return differenceInCalendarDays(current, this.today) > 0;
  };

  disabledDateTime: DisabledTimeFn = () => {
    return {
      nzDisabledHours: () => this.range(0, 24).splice(4, 20),
      nzDisabledMinutes: () => this.range(30, 60),
      nzDisabledSeconds: () => [55, 56]
    };
  };

  disabledRangeTime: DisabledTimeFn = (_value, type?: DisabledTimePartial) => {
    if (type === 'start') {
      return {
        nzDisabledHours: () => this.range(0, 60).splice(4, 20),
        nzDisabledMinutes: () => this.range(30, 60),
        nzDisabledSeconds: () => [55, 56]
      };
    }
    return {
      nzDisabledHours: () => this.range(0, 60).splice(20, 4),
      nzDisabledMinutes: () => this.range(0, 31),
      nzDisabledSeconds: () => [55, 56]
    };
  };
}
~
~

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

expand codeexpand code
import { Component } from '@angular/core';
import endOfMonth from 'date-fns/end_of_month';

@Component({
  selector: 'nz-demo-date-picker-presetted-ranges',
  template: `
    <nz-range-picker [nzRanges]="ranges1" ngModel (ngModelChange)="onChange($event)"></nz-range-picker>
    <br />
    <nz-range-picker
      [nzRanges]="ranges1"
      nzShowTime
      nzFormat="yyyy/MM/dd HH:mm:ss"
      ngModel
      (ngModelChange)="onChange($event)"
    ></nz-range-picker>
  `,
  styles: [
    `
      nz-date-picker,
      nz-month-picker,
      nz-range-picker,
      nz-week-picker {
        margin: 0 8px 12px 0;
      }
    `
  ]
})
export class NzDemoDatePickerPresettedRangesComponent {
  ranges1 = { Today: [new Date(), new Date()], 'This Month': [new Date(), endOfMonth(new Date())] };
  ranges2 = { Today: [new Date(), new Date()], 'This Month': [new Date(), endOfMonth(new Date())] };

  onChange(result: Date[]): void {
    console.log('From: ', result[0], ', to: ', result[1]);
  }
}

Determing which panel to show with nzMode and nzOnPanelChange.

expand codeexpand code
import { Component } from '@angular/core';

@Component({
  selector: 'nz-demo-date-picker-mode',
  template: `
    <nz-date-picker
      [nzMode]="dateMode"
      nzShowTime
      (nzOnOpenChange)="handleDateOpenChange($event)"
      (nzOnPanelChange)="handleDatePanelChange($event)"
    >
    </nz-date-picker>
  `,
  styles: [
    `
      nz-date-picker,
      nz-month-picker,
      nz-range-picker,
      nz-week-picker {
        margin: 0 8px 12px 0;
      }
    `
  ]
})
export class NzDemoDatePickerModeComponent {
  dateMode = 'time';

  handleDateOpenChange(open: boolean): void {
    if (open) {
      this.dateMode = 'time';
    }
  }

  handleDatePanelChange(mode: string): void {
    console.log('handleDatePanelChange: ', mode);
  }
}

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);

There are four kinds of picker:

  • nz-date-picker
  • nz-month-picker
  • nz-range-picker
  • nz-week-picker

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

Common API#

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

PropertyDescriptionTypeDefault
[nzAllowClear]Whether to show clear buttonbooleantrue
[nzAutoFocus]get focus when component mountedbooleanfalse
[nzClassName]picker classNamestring''
[nzDateRender]custom rendering function for date cells (Not support by month-picker/year-picker)TemplateRef<Date> | string | ((d: Date) => TemplateRef<Date> | string)-
[nzDisabled]determine whether the nz-date-picker is disabledbooleanfalse
[nzDisabledDate]specify the date that cannot be selected(current: Date) => boolean-
[nzLocale]localization configurationobjectdefault
[nzOpen]open state of pickerboolean-
[nzPopupStyle]to customize the style of the popup calendarobject{}
[nzDropdownClassName]to customize the className of the popup calendarstring-
[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'-
[nzStyle]to customize the style of the input boxobject{}
(nzOnOpenChange)a callback emitter, can be executed whether the popup calendar is popped up or closedEventEmitter<boolean>-

nz-date-picker#

PropertyDescriptionTypeDefault
[ngModel]DateDate-
[nzDisabledTime]to specify the time that cannot be selected(current: Date) => { nzDisabledHours, nzDisabledMinutes, nzDisabledSeconds }-
[nzFormat]to set the date format, see nzFormat special instructionsstring"yyyy-MM-DD"
[nzRenderExtraFooter]render extra footer in panelTemplateRef | string | (() => TemplateRef | string)-
[nzShowTime]to provide an additional time selectionobject | booleanTimePicker Options
[nzShowToday]whether to show "Today" buttonbooleantrue
[nzPlaceHolder]placeholder of date inputstring-
(nzOnOk)callback when click ok buttonEventEmitter<Date>-
(ngModelChange)Date change callbackEventEmitter<Date>-

nz-year-picker#

PropertyDescriptionTypeDefault
[ngModel]DateDate-
[nzFormat]to set the date format, see nzFormat special instructionsstring"yyyy"
[nzRenderExtraFooter]render extra footer in panelTemplateRef | string | (() => TemplateRef | string)-
[nzPlaceHolder]placeholder of date inputstring-
(ngModelChange)Date change callbackEventEmitter<Date>-

nz-month-picker#

PropertyDescriptionTypeDefault
[ngModel]DateDate-
[nzFormat]to set the date format, see nzFormat special instructionsstring"yyyy-MM"
[nzRenderExtraFooter]render extra footer in panelTemplateRef | string | (() => TemplateRef | string)-
[nzPlaceHolder]placeholder of date inputstring-
(ngModelChange)Date change callbackEventEmitter<Date>-

nz-week-picker#

PropertyDescriptionTypeDefault
[ngModel]DateDate-
[nzFormat]to set the date format, see nzFormat special instructionsstring"yyyy-ww"
[nzPlaceHolder]placeholder of date inputstring-
(ngModelChange)Date change callbackEventEmitter<Date>-

nz-range-picker#

PropertyDescriptionTypeDefault
[ngModel]DateDate[]-
[nzDisabledTime]to specify the time that cannot be selected(current: Date, partial: 'start' | 'end') => { nzDisabledHours, nzDisabledMinutes, nzDisabledSeconds }-
[nzFormat]to set the date format, see nzFormat special instructionsstring"yyyy-MM-dd"
[nzRanges]preseted ranges for quick selection{ [ key: string ]: Date[] } | { [ key: string ]: () => Date[] }-
[nzRenderExtraFooter]render extra footer in panelTemplateRef | string | (() => TemplateRef | string)-
[nzShowTime]to provide an additional time selectionobject | booleanTimePicker Options
[nzPlaceHolder]placeholder of date inputstring[]-
(nzOnOk)click ok callbackEventEmitter<Date[]>-
(ngModelChange)Date change callbackEventEmitter<Date[]>-
(nzOnCalendarChange)The start time or the end time of the range change callbackEventEmitter<Date[]>-

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

nzFormat special instructions#

Date formatting currently supports two methods: DatePipe (default, syntax reference) and Date-fns (syntax reference, see How to format a date using Date-fns).