@toverux/ngx-sweetalert2 v4.0.0

This is not a regular API wrapper for SweetAlert (which already works very well alone), it intends to provide Angular-esque utilities on top of it.

:point_right: Version 7 is out! If you come from v6.x, read the release notes!

:point_right: Version 6 is out! If you come from v5.x, read the release notes!

:point_right: Before posting an issue, please check that the problem isn't on SweetAlert's side.

• Installation & Usage
• [swal] directive — for simple, one-liner dialogs
• <swal> component — for advanced use cases and extended Swal2 API coverage
• *swalPortal directive — use Angular templates in <swal>

:package: Installation & Usage

1) Install ngx-sweetalert2 and sweetalert2 via the npm registry:

npm install --save sweetalert2 @sweetalert2/ngx-sweetalert2

:arrow_double_up: Always upgrade SweetAlert2 when you upgrade ngx-sweetalert2. The latter is statically linked with SweetAlert2's type definitions.

2) Import the module:

import { SweetAlert2Module } from '@sweetalert2/ngx-sweetalert2';

@NgModule({
    //=> Basic usage (forRoot can also take options, see details below)
    imports: [SweetAlert2Module.forRoot()],

    //=> In submodules only:
    imports: [SweetAlert2Module],

    //=> In submodules only, overriding options from your root module:
    imports: [SweetAlert2Module.forChild({ /* options */ })]
})
export class AppModule {
}

That's it! By default, SweetAlert2 will be lazy-loaded, only when needed, from your local dependency of sweetalert2, using the import() syntax under the hood.

:link: API

SwalDirective

Add the [swal] attribute to an element to show a simple modal when that element is clicked.

To define the modal contents, you can pass a SweetAlertOptions (provided by sweetalert2) object, or a simple array of strings, of format [title: string, text: string (, icon: string)].

Simple dialog:

<button [swal]="['Oops!', 'This is not implemented yet :/', 'warning']">
  Do it!
</button>

More advanced (input in dialog, dismissal handling):

<button
  [swal]="{ title: 'Enter your email', input: 'email' }"
  (confirm)="saveEmail($event)"
  (cancel)="handleRefusalToSetEmail($event)">

  Set my e-mail address
</button>

export class MyComponent {
  public saveEmail(email: string): void {
    // ... save user email
  }

  public handleRefusalToSetEmail(dismissMethod: string): void {
    // dismissMethod can be 'cancel', 'overlay', 'close', and 'timer'
    // ... do something
  }
}

The directive can also take a reference to a <swal> component for more advanced use cases:

<button [swal]="deleteSwal" (confirm)="deleteFile(file)">
  Delete {{ file.name }}
</button>

<swal #deleteSwal ...></swal>

SwalComponent

The library also provides a component, that can be useful for advanced use cases, or when you [swal] has too much options.

The component also allows you to use Angular dynamic templates inside the SweetAlert (see the *swalPortal directive for that).

Simple example:

<swal
  #deleteSwal
  title="Delete {{ file.name }}?"
  text="This cannot be undone"
  icon="question"
  [showCancelButton]="true"
  [focusCancel]="true"
  (confirm)="deleteFile(file)">
</swal>

With [swal]:
<button [swal]="deleteSwal">Delete {{ file.name }}</button>

Or DIY:
<button (click)="deleteSwal.fire()">Delete {{ file.name }}</button>

You can access the dialog from your TypeScript code-behind like this:

class MyComponent {
  @ViewChild('deleteSwal') private deleteSwal: SwalComponent;
}

You can pass native SweetAlert2 options via the swalOptions input, just in the case you need that:

<swal [swalOptions]="{ confirmButtonText: 'I understand' }"></swal>

By the way: every "special" option, like swalOptions, that are not native options from SweetAlert2, are prefixed with swal.

You can catch other modal lifecycle events than (confirm) or (cancel):

<swal
  (render)="onRender($event)"
  (beforeOpen)="onBeforeOpen($event)"
  (open)="onOpen($event)"
  (close)="onClose($event)"
  (afterClose)="onAfterClose()">
</swal>

public onBeforeOpen(event: BeforeOpenEvent): void {
  // You can access the modal's native DOM node:
  console.log(event.modalElement);
}

SwalPortalDirective

The *swalPortal structural directive lets you use Angular dynamic templates inside SweetAlerts.

The name "portal" is inspired by React or Angular CDK portals. The directive will replace certain parts of the modal (aka. swal targets) with embedded Angular views.

This allows you to have data binding, change detection, and use every feature of the Angular template syntax you want, just like if the SweetAlert was a normal Angular component (it's not at all).

<swal title="SweetAlert2 Timer">
  <div *swalPortal class="alert alert-info">
    <strong>{{ elapsedSeconds }}</strong> seconds elapsed since the modal was opened.
  </div>
</swal>

Using a structural directives allows us to take your content as a template, instantiate it lazily when needed (ie. when the modal is shown), and putting it in a native DOM element that is originally outside the scope of your Angular app.

This examples sets the main content of the modal, where the text property is usually rendered when SweetAlert2 is in charge. But you can also target the title, the footer, or even the confirm button, and more!

You just have to change the target of the portal (content is the default target). First, inject this little service in your component:

import { SwalPortalTargets } from '@sweetalert2/ngx-sweetalert2';

export class MyComponent {
  public constructor(public readonly swalTargets: SwalPortalTargets) {
  }
}

And then, set the appropriate target as the value of *swalPortal, here using two portals, the first one targeting the modal's content (this is the default), and the other one targeting the confirm button text.

<swal title="Fill the form, rapidly" (confirm)="sendForm(myForm.value)">
  <!-- This form will be displayed as the alert main content
       Targets the alert's main content zone by default -->
  <form *swalPortal [formControl]="myForm">
    ...
  </form>

  <!-- This targets the confirm button's inner content
       Notice the usage of ng-container to avoid creating an useless DOM element inside the button -->
  <ng-container *swalPortal="swalTargets.confirmButton">
    Send ({{ secondsLeft }} seconds left)
  </ng-container>
</swal>

We have the following targets: closeButton, title, content, actions, confirmButton, cancelButton, and footer.

These targets are mostly provided by SweetAlert2 and made available in the right format for swal portals by this library, but you can also make your own if you need to (take inspiration from the original service source). Those are just variables containing a function that returns a modal DOM element, not magic. The magic is inside the directive ;)