ngneat
A simple to use, highly customizable, and powerful modal for Angular Applications
Features
✅ TemplateRef/Component Support
✅ Dialog Guards Support
✅ Resizable
✅ Draggable
✅ Multiple Dialogs Support
✅ Customizable
Installation
npm i @ngneat/dialog
Usage
Using a Component
First, create the component to be displayed in the modal:
import { DialogService, DialogRef } from '@ngneat/dialog';
interface Data {
title: string;
}
@Component({
template: `
<h1>{{ title }}</h1>
<button (click)="ref.close(true)">Close</button>
`,
standalone: true,
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class HelloWorldComponent {
ref: DialogRef<Data, boolean> = inject(DialogRef);
get title() {
if (!this.ref.data) return 'Hello world';
return this.ref.data.title;
}
}Inside the component, you'll have access to a DialogRef provider. You can call its close() method to close the current modal. You can also pass data that'll be available for any subscribers to afterClosed$.
💡 Tip
A publicly accessible property of type
DialogRef<Input, Output>on your component will be used to infer the input and output types of your component.
Now we can use the DialogService to open the modal and display the component:
import { DialogService } from '@ngneat/dialog';
@Component({
standalone: true,
template: ` <button (click)="open()">Open</button> `,
})
export class AppComponent implements OnInit {
private dialog = inject(DialogService);
ngOnInit() {
const dialogRef = this.dialog.open(HelloWorldComponent, {
// data is typed based on the passed generic
data: {
title: '',
},
});
}
}DialogRef API
The DialogRef instance exposes the following API:
afterClosed$- An observable that emits after the modal closes:
const dialogRef = this.dialog.open(HelloWorldComponent);
dialogRef.afterClosed$.subscribe((result) => {
console.log(`After dialog has been closed ${result}`);
});backdropClick$- An observable that emits when the user clicks on the modal backdrop:
const dialogRef = this.dialog.open(HelloWorldComponent);
dialogRef.backdropClick$.subscribe(() => {
console.log('Backdrop has been clicked');
});resetDrag- A method that can be called to reset the dragged modal to the middle of the screen. An offset can be given as the first parameter to position it different from the center:
dialogRef.resetDrag();
dialogRef.resetDrag({ x: 100, y: 0 });beforeClose- A guard that should return aboolean, anobservable, or apromiseindicating whether the modal can be closed:
dialogRef.beforeClose((result) => dialogCanBeClosed);
dialogRef.beforeClose((result) => this.service.someMethod(result));ref.data- A reference to thedatathat is passed by the component opened in the modal:
import { DialogService, DialogRef } from '@ngneat/dialog';
@Component({
template: `
<h1>{{ ref.data.title }}</h1>
<button (click)="ref.close()">Close</button>
`,
standalone: true,
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class HelloWorldComponent {
ref: DialogRef<Data> = inject(DialogRef);
}ref.updateConfig- An update function for the config, a common use case would be a reusable component setting its own common properties:
import { DialogService, DialogRef } from '@ngneat/dialog';
@Component({
template: `
<h1>{{ ref.data.title }}</h1>
<button (click)="ref.close()">Close</button>
`,
standalone: true,
changeDetection: ChangeDetectionStrategy.OnPush,
})
export class MyVeryCommonDialogComponent {
ref: DialogRef<Data> = inject(DialogRef);
constructor() {
this.ref.updateConfig({
height: '200px',
width: '400px',
});
}
}You can only update the config before the dialog is opened in the component's constructor.
The library also provides the dialogClose directive helper, that you can use to close the modal:
import { DialogService, DialogCloseDirective } from '@ngneat/dialog';
@Component({
standalone: true,
imports: [DialogCloseDirective],
template: `
<h1>Hello World</h1>
<button dialogClose>Close</button>
<button [dialogClose]="result">Close with result</button>
`,
})
export class HelloWorldComponent {}Using a TemplateRef
Sometimes it can be overkill to create a whole component. In these cases, you can pass a reference to an <ng-template>:
import { DialogService } from '@ngneat/dialog';
@Component({
selector: 'app-root',
standalone: true,
template: `
<ng-template #modalTpl let-ref>
<h1>Hello World</h1>
<button (click)="ref.close()">Close</button>
</ng-template>
<button (click)="open(modalTpl)">Open</button>
`,
})
export class AppComponent {
private dialog = inject(DialogService);
open(tpl: TemplateRef<any>) {
this.dialog.open(tpl);
}
}Note that in this case, you can access the ref object by using the $implicit context property.
Passing Data to the Modal Component
Sometimes we need to pass data from the opening component to our modal component. In these cases, we can use the data property, and use it to pass any data we need:
import { DialogService } from '@ngneat/dialog';
@Component({
standalone: true,
template: ` <button (click)="open()">Open</button> `,
})
export class AppComponent implements OnInit {
private dialog = inject(DialogService);
private title = 'Dialog title';
open() {
const dialogRef = this.dialog.open(HelloWorldComponent, {
data: {
title: this.title,
},
});
}
}Now we can access it inside our modal component or template, by using the ref.data property.
Dialog Options
Global Options
In the forRoot method when importing the dialog module in the app module you can specify the following options that will be globally applied to all dialog instances.
closeButton- Whether to display an 'X' for closing the modal (default is true).enableClose- Whether a click on the backdrop, or press of the escape button, should close the modal (default is true), see enable close.backdrop- Whether to show the backdrop element (default is true).resizable- Whether the modal show be resizeable (default is false).draggable- Whether the modal show be draggable (default is false).draggableConstraint- When draggable true, whether the modal should be constraint to the window. Usenonefor no constraint,bounceto have the modal bounce after it is released andconstrainto constrain while dragging (default isnone).size- Set the modal size according to your global custom sizes (default ismd).windowClass- Add a custom class to the modal container.width- Set a custom width (default unit ispx).minWidth- Set a custom min-width (default unit ispx).maxWidth- Set a custom max-width (default unit ispx).height- Set a custom height (default unit ispx).minHeight- Set a custom min-height (default unit ispx).maxHeight- Set a custom max-height (default unit ispx).container- A custom element to which we append the modal (default isbody).
import { provideDialogConfig } from '@ngneat/dialog';
bootstrapApplication(AppComponent, {
providers: [
provideDialogConfig({
closeButton: boolean,
enableClose:
boolean |
'onlyLastStrategy' |
{
escape: boolean | 'onlyLastStrategy',
backdrop: boolean | 'onlyLastStrategy',
},
backdrop: boolean,
resizable: boolean,
draggable: boolean,
overflow: boolean,
draggableConstraint: none | bounce | constrain,
sizes,
size: sm | md | lg | fullScreen | string,
windowClass: string,
width: string | number,
minWidth: string | number,
maxWidth: string | number,
height: string | number,
minHeight: string | number,
maxHeight: string | number,
}),
],
});Instance Options
For each dialog instance you open you can specify all the global options and also the following 3 options.
id- The modal's unique id, the defaults are:- If a component is passed - the component's name (e.g.
MyCustomDialog). - Otherwise, a random id is given.
[!Note]
while not required, it is recommended to set an id in order to prevent unwanted multiple instances of the same dialog.
- If a component is passed - the component's name (e.g.
vcr- A customViewContainerRefto use.data- Adataobject that will be passed to the modal template or component.
this.dialog.open(compOrTemplate, {
//...
// all global options expect sizes
//...
id: string,
vcr: ViewContainerRef,
data: {},
});Enable close
The enableClose property can be configured for each dialog.
It can either be an object with the keys escape and backdrop for more granular control,
or one of the values described below directly.
The latter will apply the set value to both close triggers (escape and backdrop).
If set to true, clicking on the backdrop or pressing the escape key will close the modal.
If set to false, this behavior will be disabled.
Additionally, the property can be set to the string value 'onlyLastStrategy'.
In this case, the behavior will only apply to the last dialog that was opened, and not to any other dialog.
By default, this should be the top-most dialog and behave as true.
Custom Sizes
The default sizes config is:
{
sizes: {
sm: {
height: 'auto',
width: '400px',
},
md: {
height: 'auto',
width: '560px',
},
lg: {
height: 'auto',
width: '800px',
},
fullScreen: {
height: '100%',
width: '100%',
},
}
}You can override it globally by using the sizes option:
bootstrapApplication(AppComponent, {
providers: [
provideDialogConfig({
sizes: {
sm: {
width: 300, // 300px
minHeight: 250, // 250px
},
md: {
width: '60vw',
height: '60vh',
},
lg: {
width: '90vw',
height: '90vh',
},
fullScreen: {
width: '100vw',
height: '100vh',
},
},
}),
],
});Styling
You can customize the styles with these classes:
ngneat-dialog {
.ngneat-dialog-backdrop {
// backdrop styles
.ngneat-dialog-content {
// dialog content, where your component/template is placed
.ngneat-drag-marker {
// draggable marker
}
.ngneat-close-dialog {
// 'X' icon for closing the dialog
}
}
}
}