{"id":13729318,"url":"https://github.com/maximelafarie/ngx-smart-modal","last_synced_at":"2025-04-08T10:33:26.117Z","repository":{"id":38694732,"uuid":"95038317","full_name":"maximelafarie/ngx-smart-modal","owner":"maximelafarie","description":"Modal/Dialog component crafted for Angular (Ivy-compatible)","archived":false,"fork":false,"pushed_at":"2024-08-06T22:23:54.000Z","size":7424,"stargazers_count":325,"open_issues_count":21,"forks_count":88,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-01T09:25:21.307Z","etag":null,"topics":["angular","angular-cli","angular-ivy","dialog","hacktoberfest","library","modal","modal-dialogs","modals","ngx-smart-modal","npm","npm-module","npm-package","yarn"],"latest_commit_sha":null,"homepage":"https://maximelafarie.com/ngx-smart-modal/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maximelafarie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-21T19:23:24.000Z","updated_at":"2024-12-20T14:57:12.000Z","dependencies_parsed_at":"2023-02-06T20:45:55.933Z","dependency_job_id":"ebd721c4-d70a-4289-8336-d7314f8a28f4","html_url":"https://github.com/maximelafarie/ngx-smart-modal","commit_stats":{"total_commits":183,"total_committers":32,"mean_commits":5.71875,"dds":0.3825136612021858,"last_synced_commit":"90616b5876de6e7db0913fb65fb66f5e01ba1a58"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximelafarie%2Fngx-smart-modal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximelafarie%2Fngx-smart-modal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximelafarie%2Fngx-smart-modal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maximelafarie%2Fngx-smart-modal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maximelafarie","download_url":"https://codeload.github.com/maximelafarie/ngx-smart-modal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247305932,"owners_count":20917208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","angular-cli","angular-ivy","dialog","hacktoberfest","library","modal","modal-dialogs","modals","ngx-smart-modal","npm","npm-module","npm-package","yarn"],"created_at":"2024-08-03T02:00:58.529Z","updated_at":"2025-04-08T10:33:26.083Z","avatar_url":"https://github.com/maximelafarie.png","language":"TypeScript","funding_links":[],"categories":["UI Components","Table of contents"],"sub_categories":["Overlay","Third Party Components"],"readme":"# ngx-smart-modal\n\n[![Join the chat at https://gitter.im/ngx-smart-modal/Lobby](https://badges.gitter.im/ngx-smart-modal/Lobby.svg)](https://gitter.im/ngx-smart-modal/Lobby?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge) ![ci](https://github.com/maximelafarie/ngx-smart-modal/actions/workflows/ci.yml/badge.svg) [![npm version](https://badge.fury.io/js/ngx-smart-modal.svg)](https://badge.fury.io/js/ngx-smart-modal) [![npm downloads](https://img.shields.io/npm/dm/ngx-smart-modal.svg)](https://npmjs.org/ngx-smart-modal) [![codecov](https://codecov.io/gh/maximelafarie/ngx-smart-modal/branch/master/graph/badge.svg?token=7Zfad6MCQR)](https://codecov.io/gh/maximelafarie/ngx-smart-modal)\n\nngx-smart-modal is a lightweight and very complete Angular library for managing modals inside any Angular project.\n\n## No external library, pure Angular! 🤘\n\nTo avoid having to download a CSS library when using this package, simply use our built-in SCSS/CSS file with custom animations and overloadable variables. So you don't have to use a CSS library you don't want! What's more, it doesn't use jQuery either!\n\n## CSS-framework-agnostic\n\nBecause we want to be as neutral as we can, we made it very flexible for you to style it with any CSS framework. So if your project uses a framework which is shipped with some modal styles, you simply have to pick up its class names and set the main class in the [customClass]=\"'modal'\" (e.g.: bootstrap). And the rest of the modal DOM elements has just to be set into the ngx-smart-modal component (e.g.: `modal-dialog`, `modal-content`, `modal-header`, etc.).\n\n## Features\n\n* Handle large quantity of modals anywhere in your app\n* Customize the style of your modals through custom CSS classes and SCSS variables!\n* No external CSS library is used so you can easily override the modals default style\n* Pass data to any modal and retrieve it very simply in the modal view (or anywhere else)\n* Events on open, close, dismiss, escape and more for each modal\n* Manage all your modal stack and data with very fast methods\n* Smart z-index computation (no ugly glitches or problems with a modal inside another)\n* A modal in a modal in a modal in a modal... I guess you got it!\n* AoT compilation support\n\n## How it works\n\nBasically, imagine that the component is based on a service that stores any modals you create in order to let you pick them up and manage them anywhere in your app at any time.\n![sequence diagram](assets/sequence_diagram.png)\n\n## Browsers Support\n\n| Chrome | Firefox | Edge | Safari | Opera |\n| ------ | ------- | ---- | ------ | ----- |\n| \u003e 75   | \u003e 60    | \u003e 17 | \u003e 5.1  | \u003e 60  |\n\n\u003csub\u003eBased on [browserl.ist](https://browserl.ist/?q=+%3E+0.5%25%2C+last+2+versions%2C+Firefox+ESR%2C+not+dead%2C+not+IE+9-11)\u003c/sub\u003e\n\n## Installation\n\n```sh\nnpm i ngx-smart-modal --save\n```\n\n## Which version should I use?\n\nIf your project uses a version of Angular lower than 14 (or non-Ivy), use version `\u003c=7.4.1`. Otherwise, use the latest version `\u003e=14.x`.\n\n## How to use\n\n### Import the module\n\nAdd NgxSmartModalModule (with .forRoot() or .forChild() depending if the module which you import the library into is the main module of your project or a nested module) and NgxSmartModalService to your project NgModule\n\n```ts\nimport { NgModule } from '@angular/core';\nimport { BrowserModule } from '@angular/platform-browser';\n\nimport { AppRoutingModule } from './app-routing.module';\nimport { AppComponent } from './app.component';\nimport { NgxSmartModalModule } from 'ngx-smart-modal';\n\n@NgModule({\n  declarations: [\n    AppComponent\n  ],\n  imports: [\n    BrowserModule,\n    AppRoutingModule,\n    NgxSmartModalModule.forRoot()\n  ],\n  providers: [\n  ],\n  bootstrap: [AppComponent]\n})\nexport class AppModule { }\n```\n\n### Import the styles\n\nAnd import ngx-smart-modal.scss or ngx-smart-modal.css in a global style file (e.g. styles.scss or styles.css in classic Angular projects or any other scss/css file it imports). Example with styles.scss:\n\n```scss\n/* You can add global styles to this file, and also import other style files */\n@import \"~ngx-smart-modal/styles/ngx-smart-modal\"\n```\n\n## Manipulate modals\n\n### from the template\n\nYou can use modals directly in your component's template like this:\n\n```html\n\u003cngx-smart-modal #myModal identifier=\"myModal\"\u003e\n  \u003ch1\u003eTitle\u003c/h1\u003e\n  \u003cp\u003eSome stuff...\u003c/p\u003e\n\n  \u003cbutton (click)=\"myModal.close()\"\u003eClose\u003c/button\u003e\n\u003c/ngx-smart-modal\u003e\n```\n\nAt this point, the modal instance is stored in the NgxSmartModalService. You can do absolutely what you want with it, anywhere in your app. For example, from a component :\n\n```ts\nimport { Component } from '@angular/core';\nimport { NgxSmartModalService } from 'ngx-smart-modal';\n\n@Component({\n  // ...\n})\nexport class AppComponent {\n  constructor(public ngxSmartModalService: NgxSmartModalService) {\n  }\n}\n```\n\nThen in the AppComponent view you can open any modal with no need to be in the same view:\n\n```html\n\u003cbutton (click)=\"ngxSmartModalService.getModal('myModal').open()\"\u003eOpen myModal\u003c/button\u003e\n```\n\n### with class reference (since 7.2.0)\n\n```ts\nimport { Component } from '@angular/core';\n\nimport { MyComponent } from 'xxxx';\n\nimport { NgxSmartModalService } from 'ngx-smart-modal';\n\n@Component({\n  // ...\n})\nexport class AppComponent {\n  // If Angular \u003c 8\n  // @ViewChild(TemplateRef) tpl: TemplateRef\u003cany\u003e;\n\n  // If Angular \u003e= 8\n  @ViewChild(TemplateRef, { static: false }) tpl: TemplateRef\u003cany\u003e;\n\n  constructor(private ngxSmartModalService: NgxSmartModalService, private vcr: ViewContainerRef) {\n    // simple text content\n    this.ngxSmartModalService.create('myModal1', 'content', vcr).open();\n\n    // component\n    this.ngxSmartModalService.create('myModal2', MyComponent, vcr).open();\n\n    // or templateRef\n    this.ngxSmartModalService.create('myModal3', this.tpl, vcr).open();\n  }\n}\n```\n\n## Manipulate data\n\nYou can associate data with any created modal. To do that, use the setModalData() from the `NgxSmartModalService`:\n\n```ts\nimport { AfterViewInit, Component } from '@angular/core';\nimport { NgxSmartModalService } from 'ngx-smart-modal';\n\n@Component({\n  // ...\n})\nexport class AppComponent implements AfterViewInit {\n  constructor(public ngxSmartModalService: NgxSmartModalService) {\n  }\n\n  ngAfterViewInit() {\n    const obj: Object = {\n      prop1: 'test',\n      prop2: true,\n      prop3: [{a: 'a', b: 'b'}, {c: 'c', d: 'd'}],\n      prop4: 327652175423\n    };\n\n    this.ngxSmartModalService.setModalData(obj, 'myModal');\n  }\n}\n```\n\nAfter that, you can retrieve the modal data directly from the view with the getData() modal property. To avoid any errors with unavailable data, you can use the hasData() modal property (It's dynamic. If data comes after a certain time its value will automatically change to true):\n\n```ts\n\u003cngx-smart-modal #myModal identifier=\"myModal\"\u003e\n  \u003cdiv *ngIf=\"myModal.hasData()\"\u003e\n    \u003cpre\u003e{{ myModal.getData() | json }}\u003c/pre\u003e\n  \u003c/div\u003e\n\n  \u003cbutton (click)=\"myModal.close()\"\u003eClose\u003c/button\u003e\n\u003c/ngx-smart-modal\u003e\n```\n\n## Handle events\n\n`ngx-smart-modal` comes with several built-in events:\n\n* `onOpen`: modal is opening\n* `onOpenFinished`: modal has been opened\n* `onClose`: modal is closing\n* `onCloseFinished`: modal has been closed\n* `onDismiss`: modal is closing by clicking on its backdrop\n* `onDismissFinished`: modal has been closed by clicking on its backdrop\n* `onEscape`: modal has been closed by escape key\n* `onAnyCloseEvent`: modal is closing whatever the kind of event (close / escape / dismiss)\n* `onAnyCloseEventFinished`: modal has been closed whatever the kind of event (close / escape / dismiss)\n* `visibleChange`: modal visibility has changed (regardless of the modal visibility state)\n* `onDataAdded`: data were added to the modal (using `setData()`)\n* `onDataRemoved` data were removed from the modal (using `removeData()`)\n\nYou can handle events directly from the view...\n\n```html\n\u003cngx-smart-modal #myModal identifier=\"myModal\" (onOpen)=\"log('Modal opened!')\" (onClose)=\"log('Modal closed!')\" (onDismiss)=\"log('Modal dismissed!')\"\u003e\n  \u003ch1\u003eTitle\u003c/h1\u003e\n  \u003cp\u003eSome stuff...\u003c/p\u003e\n\n  \u003cbutton (click)=\"myModal.close()\"\u003eClose\u003c/button\u003e\n\u003c/ngx-smart-modal\u003e\n```\n\n...and execute component's functions:\n\n```ts\n@Component({\n  // ...\n})\nexport class AppComponent {\n  constructor() {\n  }\n\n  public log(msg: string) {\n    console.log(msg);\n  }\n}\n```\n\nOr you can declare modal in any template (e.g.: the Rickroll demo modal)...\n\n```html\n\u003cngx-smart-modal #videoModal identifier=\"videoModal\" customClass=\"medium-modal\"\u003e\n  \u003ch1\u003eHey, I Rickrolled You!\u003c/h1\u003e\n  \u003ciframe #rickroll width=\"1280\" height=\"720\"\n          src=\"https://www.youtube.com/embed/dQw4w9WgXcQ?rel=0\u0026autoplay=1\u0026controls=0\u0026showinfo=0\u0026ecver=1\u0026enablejsapi=1\"\n          frameborder=\"0\" allowfullscreen\u003e\u003c/iframe\u003e\n\n  \u003cbutton class=\"button -dark\" (click)=\"videoModal.close()\"\u003eClose\u003c/button\u003e\n\u003c/ngx-smart-modal\u003e\n```\n\n... and listen to its events from any component:\n\n```ts\nexport class AppComponent implements AfterViewInit {\n  // ...\n  constructor(public ngxSmartModalService: NgxSmartModalService) {\n  }\n\n  ngAfterViewInit() {\n    this.ngxSmartModalService.getModal('videoModal').onOpen.subscribe((modal: NgxSmartModalComponent) =\u003e {\n      console.log('Rickroll modal opened!', modal);\n    });\n  }\n}\n```\n\n## Parameters (`INgxSmartModalOptions`)\n\n`ngx-smart-modal` comes with some parameters / options in order to make it fit your needs. The following parameters / options needs to be used like this: `\u003cngx-smart-modal [parameter-or-option-name]=\"value\"\u003e\u003c/ngx-smart-modal\u003e`\n\nThe below documentation will use the following pattern:\n\u003e `parameter/option name` (type) | default value | required? ― _description_\n\n* `closable` (boolean) | `true` ― _Show / hide the cross icon at the top right corner of the modal_\n\n* `escapable` (boolean) | `true` ― _Enable / disable the modal for listening to the escape keypress event (if pressed and this option is set to true, it will close the current opened modal or the latest opened if you have several modals opened at the same time)_\n\n* `dismissable` (boolean) | `true` ― _Enable / disable the modal backdrop for listening to the click event (if backdrop is clicked and this option is set to true, it will close the current opened modal or the latest opened if you have several modals opened at the same time)_\n\n* `identifier` (string) | `undefined` | **REQUIRED** ― _The identifiant of the modal instance. Retrieve a modal easily by its identifier_\n\n* `force` (boolean) | true ― _If true and if you declare another modal instance with the same identifier that another, the service will override it by the new you declare in the modal stack_\n\n* `customClass` (string) | `'nsm-dialog-animation-fade'` ― _All the additionnal classes you want to add to the modal (e.g.: any bootstrap modal class). You can add several classes by giving a string with space-separated class names_\n\n* `backdrop` (boolean) | `true` ― _Enable / disable the backdrop of a modal. **Tip**: when you want to encapsulate several modals, set this options at true for the parent modal and false for the others_\n\n* `hideDelay` (number) | `500` ― _Opening / closing class delay **in milliseconds**_\n\n* `autostart` (boolean) | `false` ― _Define if the modal is showing up automatically when loaded or not_\n\n* `target` (string) | `undefined` ― _Displays the modal relatively to the targeted element_\n\n## API\n\n`ngx-smart-modal` also comes with the `NgxSmartModalService` that you can use in any component like this:\n\n```ts\nimport { Component } from '@angular/core';\nimport { NgxSmartModalService } from 'ngx-smart-modal';\n\n@Component({\n  // ...\n})\nexport class AppComponent {\n  constructor(public ngxSmartModalService: NgxSmartModalService) {\n  }\n}\n```\n\n**List of available methods**:\n\n* `create(id: string, content: string or Component or TemplateRef, vcr: a ViewContainerRef reference, options: INgxSmartModalOptions)`: create a new modal and return the modal instance\n* `addModal(modalInstance: ModalInstance, force?: boolean)`: add a new modal instance\n* `getModal(id: string)`: retrieve a modal instance by its identifier\n* `get(id: string)`: retrieve a modal instance by its identifier (alias of `getModal`)\n* `open(id: string, force?: boolean)`: open a given modal\n* `close(id: string)`: close a given modal\n* `toggle(id: string, force?: boolean)`: toggle a given modal\n* `getModalStack()`: retrieve all the created modals\n* `getOpenedModals()`: retrieve all the opened modals\n* `getHigherIndex()`: get the higher `z-index` value between all the modal instances\n* `getModalStackCount()`: it gives the number of modal instances\n* `removeModal(id: string)`: remove a modal instance from the modal stack\n* `setModalData(data: any, id: string, force?: boolean)`: associate data to an identified modal\n* `getModalData(id: string)`: retrieve modal data by its identifier\n* `resetModalData(id: string)`: reset the data attached to a given modal\n* `closeLatestModal()`: Close the latest opened modal **if it has been declared as escapable**\n\n## Style \u0026 customization\n\n`ngx-smart-modal` provides built-in [SCSS variables](https://sass-lang.com/guide#topic-2) that you can override easily like it (assuming you imported `ngx-smart-modal.scss` as explained above):\n\n```scss\n/* You can add global styles to this file, and also import other style files */\n/* NgxSmartModal variables override */\n$color-overlay: rgba(0, 0, 0, .7);\n$dialog-position-top: 20%;\n\n@import \"~ngx-smart-modal/ngx-smart-modal\";\n// ...\n```\n\n_Note that variables needs to be overridden **before** `@import`!_\n\n### Available SCSS variables\n\nThe below documentation will use the following pattern:\n\u003e `parameter/option name` (type) | default value | _description_\n\n* `$color-overlay` (hex / rgb / rgba) | `rgba(0, 0, 0, .5)` ― _Modifies the modals overlay background color_\n\n* `$dialog-position-top` (px / %) | `1.75rem` ― _Defines the position of the modal from the top of the screen_\n* `$dialog-position-right` (px / %) | `1.75rem` ― _Defines the position of the modal from the right of the screen_\n* `$dialog-position-bottom` (px / %) | `1.75rem` ― _Defines the position of the modal from the bottom of the screen_\n* `$dialog-position-left` (px / %) | `1.75rem` ― _Defines the position of the modal from the left of the screen_\n\n* `$transition-duration` (duration) | `500ms` ― _Defines the transition effect duration. **Keep in mind you also need to set the same time (in ms) in the `hideDelay` modal option (see below)**_\n\n* `$transition-timing-function` (transition-timing-function Property) | `ease-in-out` ― _Specifies the speed curve of the transition effect ([available speed curves here](https://www.w3schools.com/cssref/css3_pr_transition-timing-function.asp))_\n\n### Built-in effects\n\n`ngx-smart-modal` can understand several built-in classes to open differently with a sexy effect:\n\nTo change this effect, you can use the `customClass` option (see below) but you also can define your own class names with dedicated effect and pass them to `customClass`!\n\n* ``: no class. The modal will show without any transition effect\n* `.nsm-dialog-animation-fade`: default modal effect with a simple fade effect\n* `.nsm-dialog-animation-ltr`: the modal comes with a left-to-right effect\n* `.nsm-dialog-animation-rtl`: the modal comes with a right-to-left effect\n* `.nsm-dialog-animation-ttb`: the modal comes with a top-to-bottom effect\n* `.nsm-dialog-animation-btt`: the modal comes with a bottom-to-top effect\n* `.nsm-centered`: the modal is centered vertically\n\n## Contributors\n\nMany thanks to our [awesome contributors](https://github.com/maximelafarie/ngx-smart-modal/graphs/contributors)! ♥️ Still not on the list? Let's [contribute](https://github.com/maximelafarie/ngx-smart-modal/issues)!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximelafarie%2Fngx-smart-modal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaximelafarie%2Fngx-smart-modal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaximelafarie%2Fngx-smart-modal/lists"}