Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sweetalert2/ngx-sweetalert2
Declarative, reactive, and template-driven SweetAlert2 integration for Angular
https://github.com/sweetalert2/ngx-sweetalert2
alert angular dialog modal sweetalert sweetalert2 ux
Last synced: about 10 hours ago
JSON representation
Declarative, reactive, and template-driven SweetAlert2 integration for Angular
- Host: GitHub
- URL: https://github.com/sweetalert2/ngx-sweetalert2
- Owner: sweetalert2
- License: mit
- Created: 2017-01-13T16:23:17.000Z (almost 8 years ago)
- Default Branch: main
- Last Pushed: 2024-12-08T21:34:40.000Z (4 days ago)
- Last Synced: 2024-12-09T15:45:48.052Z (3 days ago)
- Topics: alert, angular, dialog, modal, sweetalert, sweetalert2, ux
- Language: TypeScript
- Homepage:
- Size: 2.6 MB
- Stars: 660
- Watchers: 14
- Forks: 94
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-angular - ngx-sweetalert2 - Declarative, template-driven SweetAlert2 integration for Angular 4+ (Uncategorized / Uncategorized)
- awesome-angular - ngx-sweetalert2 - Declarative, reactive, and template-driven SweetAlert2 integration for Angular. (Table of contents / Third Party Components)
- fucking-awesome-angular - ngx-sweetalert2 - Declarative, reactive, and template-driven SweetAlert2 integration for Angular. (Table of contents / Third Party Components)
README
@sweetalert2/ngx-sweetalert2
Official SweetAlert2 integration for Angular
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: **Before posting an issue**, please check that the problem isn't on SweetAlert's side.
----------------
### Quick start
- [Installation & Usage](#package-installation--usage)
- [`[swal]` directive](#swaldirective) — for simple, one-liner dialogs
- [`` component](#swalcomponent) — for advanced use cases and extended Swal2 API coverage
- [`*swalPortal` directive](#swalportaldirective) — use Angular templates in ``
### Wiki recipes
- 🔌 [All possible ways of firing a modal and controlling its visibility](https://github.com/sweetalert2/ngx-sweetalert2/wiki/All-possible-ways-of-firing-a-modal-and-controlling-its-visibility)
- :wrench: [Setting global defaults (SweetAlert2 mixins)](https://github.com/sweetalert2/ngx-sweetalert2/wiki/Setting-global-defaults-(SweetAlert2-mixins))
- :art: [Use a theme from @sweetalert2/themes (and or customize SCSS variables)
](https://github.com/sweetalert2/ngx-sweetalert2/wiki/Use-a-theme-from-@sweetalert2-themes-(and-or-customize-SCSS-variables))
----------------
## :package: Installation & Usage
1) Install _ngx-sweetalert2_ and _sweetalert2_ via the npm registry:
```sh
npm install 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.
## Angular and SweetAlert2 versions compatibility table
| Angular version | Latest compatible version range | Required SweetAlert2 version range |
|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| Angular 14+ | @sweetalert2/ngx-sweetalert2@**^12.0.0** (current) | sweetalert2@**^11.0.0** |
| Angular 12, 13 | [@sweetalert2/ngx-sweetalert2@**^11.0.0**](https://github.com/sweetalert2/ngx-sweetalert2/tree/v11.0.0#readme) | sweetalert2@**^11.0.0** |
| Angular 9 to 11 | [@sweetalert2/ngx-sweetalert2@**~9.0.0**](https://github.com/sweetalert2/ngx-sweetalert2/tree/v9.0.0#readme) | sweetalert2@**^10.8.0** |
| Angular 8 | [@sweetalert2/ngx-sweetalert2@**~7.3.0**](https://github.com/sweetalert2/ngx-sweetalert2/tree/v7.3.0#readme) (:warning: NOT ~7.4.0, broken AoT metadata) | sweetalert2@**^9.7.0** |
| Angular 7 | [@sweetalert2/ngx-sweetalert2@**^5.1.0**](https://github.com/sweetalert2/ngx-sweetalert2/tree/v5.1.0#readme) | sweetalert2@**^8.5.0** |
| Angular 6 | [@sweetalert2/ngx-sweetalert2@**^5.1.0**](https://github.com/sweetalert2/ngx-sweetalert2/tree/v5.1.0#readme) | sweetalert2@**^8.5.0** |
| Angular 5 | [@sweetalert2/ngx-sweetalert2@**^5.1.0**](https://github.com/sweetalert2/ngx-sweetalert2/tree/v5.1.0#readme) | sweetalert2@**^8.5.0** |
| Angular 4 | [@toverux/ngx-sweetalert2@**^3.4.0**](https://github.com/sweetalert2/ngx-sweetalert2/tree/v3.4.0#readme) | sweetalert2@**^7.15.1** |
| Angular 2 | Try Angular 4 versions requirements, or older versions like @toverux/ngsweetalert2 | unknown |
2) Import the module:
```typescript
import { SweetAlert2Module } from '@sweetalert2/ngx-sweetalert2';
@NgModule({
//=> Basic usage (forRoot can also take options, see the wiki)
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)](https://github.com/sweetalert2/sweetalert2/blob/main/sweetalert2.d.ts) object,
or a simple array of strings, of format `[title: string, text: string (, icon: string)]`.
A simple dialog:
```html
Do it!
```
More advanced, with text input, confirmation, denial and dismissal handling:
```html
Save
```
```typescript
export class MyComponent {
public saveFile(fileName: string): void {
// ... save file
}
public handleDenial(): void {
// ... don't save file and quit
}
public handleDismiss(dismissMethod: string): void {
// dismissMethod can be 'cancel', 'overlay', 'close', and 'timer'
// ... do something
}
}
```
The directive can also take a reference to a [`` component](#swalcomponent) for more advanced use cases:
```html
Delete {{ file.name }}
```
### `SwalComponent`
The library also provides a component, that can be useful for advanced use cases, or when you `[swal]`
has too many options.
The component also allows you to use Angular dynamic templates inside the SweetAlert (see the
[`*swalPortal` directive](#swalportaldirective) for that).
Simple example:
```html
With [swal]:
Delete {{ file.name }}
Or DIY:
Delete {{ file.name }}
```
You can access the dialog from your TypeScript code-behind like this:
```ts
class MyComponent {
@ViewChild('deleteSwal')
public readonly deleteSwal!: SwalComponent;
}
```
You can pass native SweetAlert2 options via the `swalOptions` input, just in the case you need that:
```html
```
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), (deny) or (cancel):
```html
```
```typescript
export class MyComponent {
public swalWillOpen(event: WillOpenEvent): void {
// Most events (those using $event in the example above) will let you access the modal native DOM node, like this:
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).
```html
{{ elapsedSeconds }} seconds elapsed since the modal was opened.
```
Using a structural directives allows us to take your content as a template, instantiate it lazily when needed
(i.e. when the modal is shown), and putting it in a native DOM element that is originally outside the scope of
your Angular app.
In this example we set the main content of the modal, where the `text` property is usually rendered when SweetAlert2
is in charge.
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:
```typescript
import { SwalPortalTargets } from '@sweetalert2/ngx-sweetalert2';
export class MyComponent {
public constructor(public readonly swalTargets: SwalPortalTargets) {
}
}
```
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.
```html
...
Send ({{ secondsLeft }} seconds left)
```
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 ;)