# ngx-sweetalert2: an Angular wrapper built around templates, not calls

> ngx-sweetalert2 is the official SweetAlert2 integration for Angular, and the README is quick to say what it is not: a regular API wrapper. It ships three ways to open a dialog, a directive, a component and a portal directive for template content, and its version numbers are tightly coupled to Angular and SweetAlert2 releases.

**sweetalert2/ngx-sweetalert2** — Declarative, reactive, and template-driven SweetAlert2 integration for Angular

- Repository: https://github.com/sweetalert2/ngx-sweetalert2
- Stars: 673 · Forks: 98
- Language: TypeScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/sweetalert2-ngx-sweetalert2

## Three ways to open a dialog, not one function call

The README opens with a qualification that sets the scope of the whole library: this is not a regular API wrapper for SweetAlert, which already works well on its own. The intent is to provide Angular style utilities on top of it.

Those utilities come in three shapes, and the quick start lists all three. The [swal] directive handles simple, one-liner dialogs by binding data to a plain element. The <swal> component covers advanced use cases and gives wider coverage of the SweetAlert2 API surface. The *swalPortal directive is the one that lets you use Angular templates inside a <swal> block, which is how you put a real component, with its own bindings and events, into the dialog body.

The practical difference from calling the library directly is where the code lives. A direct call puts the dialog definition in a service or a component method. Here, the dialog definition can be markup, and the portal directive means the dialog content is a template rather than a string of HTML passed to a parameter.

The library also states its own support policy in the README: before posting an issue, check that the problem is not on the SweetAlert's side, since a large share of reported problems belong to the underlying library rather than to the Angular layer.

## Providers replace the module in standalone applications

The recommended path for new applications is the standalone one, and the configuration is a provider rather than a module import. The install step pulls in both packages:

```sh
npm install sweetalert2 @sweetalert2/ngx-sweetalert2
```

The provider call goes in main.ts or app.config.ts:

```typescript
// main.ts or app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideSweetAlert2 } from '@sweetalert2/ngx-sweetalert2';

export const appConfig: ApplicationConfig = {
  providers: [
    // ... other providers
    provideSweetAlert2({
      // Optional configuration
      fireOnInit: false,
      dismissOnDestroy: true,
    }),
  ],
};
```

Two of those options carry real behaviour. fireOnInit set to false means a <swal> element does not open a dialog the moment it is created, which matters for a component whose dialog should be triggered by an event rather than by rendering. dismissOnDestroy set to true means the dialog is closed when the component that owns it is destroyed, which is what stops a dialog from outliving the view that opened it.

The library then expects you to import only the pieces you use, following the standalone pattern:

```typescript
import { Component } from '@angular/core';
import { SwalComponent, SwalDirective } from '@sweetalert2/ngx-sweetalert2';

@Component({
  selector: 'my-component',
  imports: [SwalComponent, SwalDirective], // Import what you need
  template: `
    <button [swal]="['Hello', 'world!']">Click me</button>
    <swal #mySwal title="Hello world!" text="Click the button to close me"></swal>
  `,
})
export class MyComponent {}
```

The template reference on the <swal> element is what lets the component call methods on the dialog later, and the two elements show the two styles side by side, a one-liner bound to a button and a dialog declared in markup.

## The version matrix is the real dependency contract

The compatibility table is the most operationally useful part of the README, because the wrapper and the library underneath it move on separate schedules and the pair has to be matched.

Angular 22 takes @sweetalert2/ngx-sweetalert2 version 15 and requires sweetalert2 11.22.4 or newer. Angular 20 and 21 take version 14, with the same SweetAlert2 floor. Angular 18 and 19 take version 13, Angular 14 to 17 take version 12, and Angular 12 and 13 take version 11, all requiring SweetAlert2 11. Older rows keep their own floors: Angular 9 to 11 uses the 9.x line with sweetalert2 10.8.0, Angular 8 uses the 7.3.x line with a warning that 7.4.0 should not be used because of broken AoT metadata, and Angular 5, 6 and 7 all sit on the 5.1.0 line with sweetalert2 8.5.0. Angular 4 is the odd one out, pointing at the older @toverux/ngx-sweetalert2 package.

The reason the coupling is strict is stated directly: the wrapper is statically linked with SweetAlert2's type definitions, and the instruction is to always upgrade SweetAlert2 when you upgrade ngx-sweetalert2. In practice that means a version bump of this library can pull a SweetAlert2 upgrade with it, and a project that pins SweetAlert2 for its own reasons can end up fighting the wrapper's types.

Angular 8's warning is the kind of detail worth reading twice, since a single broken patch version in a minor line is exactly the sort of thing that costs an afternoon.

## The NgModule path is still documented, not deprecated

Applications that still use NgModules are covered by a second, explicitly legacy route. The install step is the same npm command, and the import is the module rather than the provider:

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

@NgModule({
```

The README notes that forRoot can also take options, referring to the same configuration surface the standalone provider exposes.

What is notable is that the legacy route is described as legacy for existing applications rather than scheduled for removal. For a large codebase still on NgModules, the upgrade path to the standalone provider is a migration project, not a one-line change, and the library still supports the old shape.

The choice between the two is not really about features. Both give you the same three ways of opening a dialog. The standalone route is the one the project recommends for new work, and the module route exists so that an application does not have to be rewritten to adopt SweetAlert2 at all.

## A library and a demo app in one repository

The repository layout shows an Angular workspace with the library and a demo application side by side. The projects/ directory holds both, angular.json is the workspace configuration, and the top level holds the library's own metadata: package.json for the workspace, LICENSE.txt, tsconfig.json, .oxfmtrc.json, .releaserc.json and bun.lock as the lockfile, with bunfig.toml for the Bun configuration.

The scripts section of the workspace manifest shows how the project is built and released. The library and the demo are built separately with ng build, a copy-files step puts README.md and LICENSE.txt into the dist folder, and the test scripts run Karma for the library and for the demo, each with a specific spec file included, using Jasmine as the test framework with a Chrome launcher and coverage reporting. Formatting and linting are handled by oxfmt and oxlint, and semantic-release handles versioning and publishing.

The release process is the reason the version numbers in the compatibility table move in lockstep with Angular releases. An Angular major version needs a new wrapper major, and the semantic-release setup with a release configuration file is what makes that publish flow repeatable.

Beyond the workspace files there is ADVANCED_USAGE.md, MIGRATION.md for major version upgrades, CONTRIBUTING.md, and an .editorconfig. The wiki recipes referenced in the README cover firing a modal and controlling its visibility, setting global defaults through SweetAlert2 mixins, and using a theme from @sweetalert2/themes or customising SCSS variables.

## The wrapper leaves the hard decisions to you

It is worth being clear about what this library does not take over, because that is where the friction shows up in real projects.

It does not decide the look. Theming lives in a separate package, @sweetalert2/themes, and customisation runs through SCSS variables, both of which are documented as wiki recipes rather than as options of the Angular wrapper. Global defaults, such as a shared mixin applied to every dialog, are also a SweetAlert2 feature configured outside the Angular layer, with the wiki pointing at the mixin documentation.

It does not replace SweetAlert2's own API either. The <swal> component gives wider coverage of the SweetAlert2 API, and the portal directive extends it to Angular templates, so the underlying library's options remain the vocabulary. The wrapper is a way of expressing that vocabulary declaratively, not a smaller API.

And the support boundary is explicit in the README. Before an issue is filed, the suggestion is to check whether the behaviour belongs to SweetAlert itself, which is an admission that a wrapper around a fast moving library will accumulate issues that are not its own. For a team, that means a dependency upgrade of sweetalert2 is a normal event, and the wrapper's compatibility table is the thing to check first when it happens.

The licence is MIT, and the package name on the registry is scoped as @sweetalert2/ngx-sweetalert2, which is what keeps it distinct from the community wrappers that predate it.

## Conclusion

Adopt ngx-sweetalert2 if you write Angular applications and want SweetAlert2 dialogs that live in templates and stay inside the framework's change detection, especially on Angular 22 where the v15 line is the matching release. Skip it if you are on Angular 5 or 6, since those are pinned to ancient package versions, or if you want a thin function call instead of a component, because the library deliberately provides Angular style utilities rather than a plain wrapper. Before installing, check the compatibility table for your Angular version, install sweetalert2 and @sweetalert2/ngx-sweetalert2 together because the types are statically linked, and read MIGRATION.md if you are moving between major versions. The last push was on 2026-06-13 and v15.0.0 was released the same day.

## FAQ

### Which version of ngx-sweetalert2 should I install for my Angular version?

The README has a compatibility table: Angular 22 uses version 15, Angular 20 and 21 use version 14, Angular 18 and 19 use version 13, and Angular 14 to 17 use version 12. The table also lists the SweetAlert2 version range each line requires.

### Do I have to upgrade sweetalert2 when I upgrade ngx-sweetalert2?

The README says to always upgrade SweetAlert2 when you upgrade ngx-sweetalert2, because the wrapper is statically linked with SweetAlert2's type definitions. Both packages are installed together with npm install sweetalert2 @sweetalert2/ngx-sweetalert2.

### How do I show an Angular template inside a SweetAlert2 dialog?

You use the *swalPortal directive inside a <swal> element, which is the part of the library intended for putting Angular templates into the dialog. The <swal> component covers the advanced API cases and the [swal] directive handles simple one-liner dialogs.

### Can I still use ngx-sweetalert2 in an application that uses NgModules?

Yes. The README documents a traditional module approach for existing applications, where you import SweetAlert2Module and can pass options to forRoot. The standalone provider approach is the recommended one for new applications using Angular 14 or newer.

## Sources

- [Issues](https://github.com/sweetalert2/ngx-sweetalert2/issues)
- [License: MIT](https://github.com/sweetalert2/ngx-sweetalert2/blob/main/LICENSE)
- [README](https://github.com/sweetalert2/ngx-sweetalert2/blob/main/README.md)
- [Releases](https://github.com/sweetalert2/ngx-sweetalert2/releases)
- [sweetalert2/ngx-sweetalert2 on GitHub](https://github.com/sweetalert2/ngx-sweetalert2)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sweetalert2-ngx-sweetalert2