Modal

Modal dialogs.

When To Use#

When requiring users to interact with the application without jumping to a new page to interrupt the user's workflow, you can use Modal to create a new floating layer over the current page for user-getting feedback or information purposes. Additionally, if you need to show a simple confirmation dialog, you can use NzModalService.confirm() and so on.

It is recommended to use the Component way to pop up the Modal so that the component logic of the popup layer can be completely isolated from the outer component and reused at any time. In the popup layer component, you can obtain Modal's component instance by injecting NzModalRef to control the behavior of the modal box.

import { NzModalModule } from 'ng-zorro-antd/modal';

Examples

Basic modal.

expand codeexpand code
      Loading...
    

To use NzModalService.confirm() to popup a confirmation modal dialog.

expand codeexpand code
      Loading...
    

In the various types of information modal dialog, only one button to close dialog is provided.

expand codeexpand code
      Loading...
    

Manually destroying a modal.

expand codeexpand code
      Loading...
    




Usage of Modal's service, examples demonstrate user-defined templates, custom components, and methods for injecting modal instances.

The template context is { $implicit: nzData, modalRef: NzModalRef } when the content or footer is templates.

expand codeexpand code
      Loading...
    

Asynchronously close a modal dialog when a user clicked OK button, for example, you can use this pattern when you submit a form.

expand codeexpand code
      Loading...
    


use nzModalFooter directive to customized footer button bar.

expand codeexpand code
      Loading...
    

To use NzModalService.confirm() to popup confirmation modal dialog. Let NzOnCancel/NzOnOk function return a promise object to delay closing the dialog.

expand codeexpand code
      Loading...
    

To customize the text of the buttons, you need to set nzOkText and nzCancelText props.

expand codeexpand code
      Loading...
    


You can use nzCentered,style.top or other styles to set position of modal dialog.

NOTE Due to Angular's style isolation, you may need to override the NgZorro style with :: ng-deep within a custom style if encapsulation: ViewEncapsulation.None is not included in the Component

expand codeexpand code
      Loading...
    

Draggable modal.

expand codeexpand code
      Loading...
    

API#

NzModalService#

The dialog is currently divided into 2 modes, normal mode and confirm box mode (for instance, the Confirm dialog, which is called by confirm/info/success/error/warning). The degree of API support for the two modes is slightly different.

PropertyDescriptionTypeDefaultGlobal Config
nzAfterOpenSpecify a EventEmitter that will be emitted when modal openedEventEmitter-
nzAfterCloseSpecify a EventEmitter that will be emitted when modal is closed completely (Can listen for parameters passed in the close/destroy method)EventEmitter-
nzBodyStyleBody style for modal body element. Such as height, padding etc.object-
nzCancelTextText of the Cancel button. Set to null to show no cancel button (this value is invalid if the nzFooter parameter is used in normal mode)stringCancel
nzCenteredCentered Modalbooleanfalse
nzClosableWhether a close (x) button is visible on top right of the modal dialog or not. Invalid value in confirm box mode (default will be hidden)booleantrue
nzOkLoadingWhether to apply loading visual effect for OK button or notbooleanfalse
nzCancelLoadingWhether to apply loading visual effect for Cancel button or notbooleanfalse
nzOkDisabledWhether to disable Ok button or notbooleanfalse
nzCancelDisabledWhether to disable Cancel button or notbooleanfalse
nzDraggableWhether modal is draggable or notbooleanfalse
nzFooterFooter content, set as footer=null when you don't need default buttons. 1. Only valid in normal mode.
2. You can customize the buttons to the maximum extent by passing a ModalButtonOptions configuration (see the case or the instructions below).
string
TemplateRef
ModalButtonOptions
OK and Cancel buttons
nzKeyboardWhether support press esc to closebooleantrue
nzMaskWhether show mask or not.booleantrue
nzMaskClosableWhether to close the modal dialog when the mask (area outside the modal) is clickedbooleantrue
nzCloseOnNavigationWhether to close the modal when the user goes backwards/forwards in history. Note that this usually doesn't include clicking on links (unless the user is using the HashLocationStrategy).booleantrue
nzDirectionDirection of the text in the modal'ltr' | 'rtl'-
nzMaskStyleStyle for modal's mask element.object-
nzOkTextText of the OK button. Set to null to show no ok button (this value is invalid if the nzFooter parameter is used in normal mode)stringOK
nzOkTypeButton type of the OK button. Consistent with the nzType of the nz-button.stringprimary
nzOkDangerDanger status of the OK button. Consistent with the nzDanger of the nz-button.booleanfalse
nzStyleStyle of floating layer, typically used at least for adjusting the position.object-
nzCloseIconCustom close iconstring|TemplateRef<void>-
nzTitleThe modal dialog's title. Leave blank to show no title. The usage of TemplateRef can refer to the casestring / TemplateRef-
nzVisibleWhether the modal dialog is visible or not. When using the <nz-modal> tag, be sure to use two-way binding, for example: [(nzVisible)]="visible".booleanfalse
nzWidthWidth of the modal dialog. When using numbers, the default unit is pxstring
number
520
nzClassNameThe class name of the modal dialogstring-
nzWrapClassNameThe class name of the container of the modal dialogstring-
nzZIndexThe z-index of the Modalnumber1000
nzOnCancelSpecify a function that will be called when a user clicks mask, close button on top right or Cancel button (If nzContent is Component, the Component instance will be put in as an argument). Note: When created with NzModalService.create, this parameter should be passed into the type of function (callback function). This function returns a promise, which is automatically closed when the execution is complete or the promise ends (return false to prevent closing)EventEmitter-
nzOnOkSpecify a EventEmitter that will be emitted when a user clicks the OK button (If nzContent is Component, the Component instance will be put in as an argument). Note: When created with NzModalService.create, this parameter should be passed into the type of function (callback function). This function returns a promise, which is automatically closed when the execution is complete or the promise ends (return false to prevent closing)EventEmitter-
nzContentContentstring / TemplateRef / Component / ng-content-
nzDataWill be a template variable when nzContent is TemplateRefobject, will be the value of the injection token NZ_MODAL_DATA when nzContent is a component-
nzIconTypeIcon type of the Icon component. Only valid in confirm box modestringquestion-circle
nzAutofocusautofocus and the position,disabled when is null'ok' | 'cancel' | 'auto' | null'auto'

NZ_MODAL_DATA#

NZ_MODAL_DATA injection token is used to retrieve nzData in the custom component. The dialog created by the service method NzModalService.create() inject a NZ_MODAL_DATA token (if nzContent is used as Component) to retrieve the parameters that have used to the 'nzContent component'

Using service to create Normal Mode modal#

You can call NzModalService.create(options) to dynamically create normal mode modals, where options is an object that supports the support given in the API above normal mode parameters

Confirm box mode - NzModalService.method()#

There are five ways to display the information based on the content's nature:

  • NzModalService.info
  • NzModalService.success
  • NzModalService.error
  • NzModalService.warning
  • NzModalService.confirm

The above items are all functions, expecting a settings object as a parameter. Consistent with the above API, some property types or initial values are different as follows:

PropertyDescriptionTypeDefault
nzOnOkSpecify a EventEmitter that will be emitted when a user clicks the OK button (If nzContent is Component, the Component instance will be put in as an argument.). This function returns a promise, which is automatically closed when the execution is complete or the promise ends (return false to prevent closing)function-
nzOnCancelSpecify a function that will be called when a user clicks mask, close button on top right or Cancel button (If nzContent is Component, the Component instance will be put in as an argument.). This function returns a promise, which is automatically closed when the execution is complete or the promise ends (return false to prevent closing)function-
nzWidthWidth of the modal dialogstring / number416
nzMaskClosableWhether to close the modal dialog when the mask (area outside the modal) is clickedbooleanfalse

All the NzModalService.methods will return a reference, and then we can close the popup by the reference.

constructor(modal
:
NzModalService
)
{
  const ref: NzModalRef = modal.info();
  ref.close(); // Or ref.destroy(); This dialog will be destroyed directly
}

Other Methods/Attributes for NzModalService#

Methods/AttributesDescriptionType
openModalsAll currently open Modal listNzModalRef[]
afterAllCloseCallback called after all Modals closed completelyObservable<void>
closeAll()Close all modalsfunction

NzModalRef#

NzModalRef object is used to control dialogs and communicate with their content

The dialog created by the service method NzModalService.xxx() will return a NzModalRef object that is used to manipulate the dialog (this object can also be obtained by dependency injection NzModalRef if nzContent is used as Component), This object has the following methods:

MethodDescription
afterOpenSame as nzAfterOpen but of type Observable<void>
afterCloseSame as nzAfterClose, but of type Observable<result:any>
close()Close (hide) the dialog. Note: When used for a dialog created as a service, this method will destroy the dialog directly (as with the destroy method)
destroy()Destroy the dialog. Note: Used only for dialogs created by the service (non-service created dialogs, this method only hides the dialog)
getContentComponent()Gets the Component instance in the contents of the dialog for nzContent. Note: When the dialog is not initialized (ngOnInit is not executed), this function will return undefined
getContentComponentRef()Gets the Component ref in the contents of the dialog for nzContent. Note: When the dialog is not initialized (ngOnInit is not executed), this function will return null
triggerOk()Manually trigger nzOnOk
triggerCancel()Manually trigger nzOnCancel
updateConfig(config: ModalOptions): voidUpdate the config

ModalButtonOptions (used to customize the bottom button)#

An array of ModalButtonOptions type can be passed to nzFooter for custom bottom buttons.

The button configuration items are as follows (along with the button component):

nzFooter: [{
  label: string; // Button text
  type? : string; // Types
  danger? : boolean; // Whether danger
  shape? : string; // Shape
  ghost? : boolean; // Whether ghost
  size? : string; // Size
  autoLoading? : boolean; // The default is true. If true, this button will automatically be set to the loading state when onClick returns a promise.

  // Tip: The `this` of below methods points to the configuration object itself. When nzContent is a component class, the contentComponentInstance parameter passed in by the method below is an instance of the component class
  // Whether to show this button
  show? : boolean | ((this: ModalButtonOptions, contentComponentInstance?: object) => boolean);
  // Whether to display loading
  loading? : boolean | ((this: ModalButtonOptions, contentComponentInstance?: object) => boolean);
  // Is it disabled
  disabled? : boolean | ((this: ModalButtonOptions, contentComponentInstance?: object) => boolean);
  // Callback of clicking
  onClick? (this: ModalButtonOptions, contentComponentInstance?: object): void | Promise<void> | any;
}]

The above configuration items can also be changed in real-time to trigger the button behavior change.

[nzModalTitle]#

Customize the title.

<div *nzModalTitle> Custom Modal Title</div>

<!-- or -->

<ng-template [nzModalTitle]> Custom Modal Title</ng-template>

[nzModalContent]#

Customize the content.

<div *nzModalContent> Custom Modal Content</div>

<!-- or -->

<ng-template [nzModalContent]> Custom Modal Content</ng-template>

[nzModalFooter]#

Customize the footer.

<div *nzModalFooter>
  <button nz-button nzType="default" (click)="handleCancel()">Custom Callback</button>
  <button nz-button nzType="primary" (click)="handleOk()" [nzLoading]="isConfirmLoading">Custom Submit</button>
</div>

<!-- or -->

<ng-template [nzModalFooter]>
  <button nz-button nzType="default" (click)="handleCancel()">Custom Callback</button>
  <button nz-button nzType="primary" (click)="handleOk()" [nzLoading]="isConfirmLoading">Custom Submit</button>
</ng-template>