ngx-custom-modal

✨ Features

- 🎯 Angular Native - Built specifically for Angular 17+
- 🎭 Standalone Components - No NgModule required
- 🚀 Signal-Based Reactivity - Optimized performance with Angular signals
- 🔗 Advanced Modal Stacking - Intelligent z-index management and focus trapping
- 🎨 Bootstrap 3, 4 & 5 Compatible - Seamless integration with all Bootstrap versions
- 📱 Mobile Friendly - Touch-optimized for mobile devices
- ⚡ Lightweight - Minimal bundle impact with performance optimization
- 🔧 TypeScript - Full type safety and IntelliSense
- 🎪 Custom Content - Support for components and HTML templates
- 🎛️ Configurable - Extensive customization options
- ♿ WCAG Compliant - Full accessibility support with screen reader compatibility
- 🔄 Route Aware - Automatic modal closing on navigation (configurable)

🚨 Version 20.0.0 - Breaking Changes Notice

$3

- 🎨 Complete CSS/SCSS Rewrite - New custom properties system and modern styling
- 🏗️ Enhanced HTML Structure - Improved accessibility with ARIA attributes
- ⚡ Signal-Based Architecture - Performance optimizations with Angular signals
- 🔧 New APIs & Services - Modal stack management and lifecycle compatibility
- 🎯 Z-Index Management - Updated from z-index: 42 to Bootstrap-standard 1050+
- 🔄 Route Change Detection - Automatic modal closing on navigation

$3

| Component | What Changed | Action Required |
| ------------------ | -------------------------------------------------------------- | -------------------------------------- |
| Custom CSS | Complete styling overhaul | Review and update custom styles |
| Event Handling | New granular events (opening, opened, closing, closed) | Update event listeners |
| Testing | New signal-based testing patterns | Update test assertions |
| Accessibility | Enhanced ARIA attributes | Verify accessibility implementations |
| Route Behavior | Automatic modal closing on navigation (enabled by default) | Configure if different behavior needed |

👉 Read Full Migration Guide in CHANGELOG.md

---

🚀 Quick Start

$3

``bash
npm install ngx-custom-modal


or

yarn add ngx-custom-modal

or

pnpm add ngx-custom-modal
`

$3

`typescript
import { NgxCustomModalComponent } from 'ngx-custom-modal';

@Component({
selector: 'app-example',
standalone: true,
imports: [NgxCustomModalComponent],
template:
Open Modal

Modal Title

Modal content goes here!

,
})
export class ExampleComponent {}
`

$3

`typescript
import { Component, signal } from '@angular/core';
import { NgxCustomModalComponent, ModalOptions } from 'ngx-custom-modal';

@Component({
selector: 'app-signal-example',
standalone: true,
imports: [NgxCustomModalComponent],
template:
Open Signal Modal

#modal
[size]="modalSize()"
[options]="modalOptions()"
(opened)="onModalOpened()"
(closed)="onModalClosed()"
>

{{ modalTitle() }}

@if (showContent()) {

{{ modalContent() }}

@for (item of items(); track item.id) {

}
}


,
})
export class SignalExampleComponent {
modalTitle = signal('Signal-Based Modal');
modalContent = signal('This modal uses Angular 17 features!');
modalSize = signal<'sm' | 'md' | 'lg' | 'xl'>('lg');
showContent = signal(true);

items = signal([
{ id: 1, name: 'Signal-based reactivity' },
{ id: 2, name: 'Control flow syntax' },
{ id: 3, name: 'Performance optimization' },
]);

modalOptions = signal({
closeOnOutsideClick: true,
closeOnEscape: true,
animation: true,
centered: true,
closeOnRouteChange: true, // Default: true - automatically close on navigation
});

onModalOpened() {
console.log('Modal opened with signals!');
}

onModalClosed() {
console.log('Modal closed');
}
}
`

📋 Examples

$3

`typescript
@Component({
template:
Open Component Modal

Component Modal

Close


,
})
export class ComponentModalExample {
componentData = { message: 'Hello from component!' };
}
`

$3

`typescript
@Component({
template:

Parent Modal

This is the parent modal with automatic stack management.

Open Child Modal

Child Modal

This is a nested modal with proper z-index handling!

,
})
export class NestedModalExample {}
`

$3

`typescript
@Component({
template:
#customModal
[closeOnOutsideClick]="false"
[closeOnEscape]="false"
[hideCloseButton]="true"
[size]="'lg'"
[centered]="true"
[scrollable]="true"
[animation]="true"
[closeOnRouteChange]="false"
customClass="my-custom-modal"
>

Custom Modal

This modal has custom configuration!

It will NOT close automatically when navigating to another route.

Manual Close


,
})
export class CustomModalExample {}
`

$3

`typescript
@Component({
template:

Options Modal

Configured via options object

,
})
export class OptionsModalExample {
modalOptions: ModalOptions = {
closeOnOutsideClick: false,
closeOnEscape: true,
customClass: 'my-modal-class',
hideCloseButton: false,
size: 'lg',
centered: true,
scrollable: false,
animation: true,
animationDuration: 300,
backdrop: 'dynamic',
keyboard: true,
focus: true,
closeOnRouteChange: true,
};
}
`

$3

`typescript
@Component({
template:

Persistent Modal

This modal will remain open even when you navigate to other pages.

Useful for shopping carts, music players, or global notifications.

Standard Modal

This modal will automatically close when navigating to other pages.

This is the default behavior for better UX.

,
})
export class RouteAwareModalExample {}
`

🔧 API Reference

$3

| Property | Type | Default | Description |
| --------------------- | ------------------------------ | ----------- | ------------------------------------ |
| closeOnOutsideClick | boolean | true | Close modal when clicking outside |
| closeOnEscape | boolean | true | Close modal when pressing Escape key |
| customClass | string | '' | Custom CSS class for the modal |
| hideCloseButton | boolean | false | Hide the default close button |
| options | ModalOptions | {} | Configuration options object |
| size | 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | Modal size |
| centered | boolean | false | Center modal vertically |
| scrollable | boolean | false | Make modal body scrollable |
| animation | boolean | true | Enable/disable animations |
| backdrop | 'static' \| 'dynamic' | 'dynamic' | Backdrop behavior |
| keyboard | boolean | true | Enable keyboard interactions |
| focus | boolean | true | Enable focus management |
| closeOnRouteChange | boolean | true | Close modal on route navigation |

$3

| Event | Type | Description |
| --------- | -------------------- | ---------------------------------- |
| opening | EventEmitter | Emitted when modal starts opening |
| opened | EventEmitter | Emitted when modal is fully opened |
| closing | EventEmitter | Emitted when modal starts closing |
| closed | EventEmitter | Emitted when modal is fully closed |

$3

| Template Ref | Type | Description |
| -------------- | ------------- | ----------------------- |
| #modalHeader | TemplateRef | Header content template |
| #modalBody | TemplateRef | Body content template |
| #modalFooter | TemplateRef | Footer content template |

$3

| Method | Returns | Description |
| ------------- | --------- | -------------------------- |
| open() | void | Opens the modal |
| close() | void | Closes the modal |
| toggle() | void | Toggles modal visibility |
| isTopMost() | boolean | Checks if modal is topmost |

$3

`typescript
interface ModalOptions {
closeOnOutsideClick?: boolean;
closeOnEscape?: boolean;
customClass?: string;
hideCloseButton?: boolean;
backdrop?: 'static' | 'dynamic';
keyboard?: boolean;
focus?: boolean;
size?: 'sm' | 'md' | 'lg' | 'xl';
centered?: boolean;
scrollable?: boolean;
animation?: boolean;
animationDuration?: number;
closeOnRouteChange?: boolean;
}
`

🔄 Route Change Behavior

$3

By default, modals will automatically close when the user navigates to a different route. This provides a better user experience and prevents modals from appearing in unexpected contexts.

`typescript
// Default behavior - modal closes on navigation




// Explicitly enabled



`

$3

For specific use cases where you want the modal to persist across route changes (shopping carts, media players, global notifications), you can disable this behavior:

`typescript
// Modal persists across route changes




// Via options object
modalOptions: ModalOptions = {
closeOnRouteChange: false,
// other options...
};
`

$3

If you're upgrading from a previous version and have modals that were designed to persist across routes, you'll need to explicitly set closeOnRouteChange: false:

`typescript
// Before v20.0.0 (modals persisted by default)




// After v20.0.0 (to maintain same behavior)



`

🎨 Styling

$3

The library comes with modern CSS custom properties for easy theming:

`css
:root {
/ Modal backdrop /
--modal-backdrop-bg: rgba(0, 0, 0, 0.5);
--modal-backdrop-blur: 2px;

/ Modal content /
--modal-content-bg: #fff;
--modal-content-border: 1px solid rgba(0, 0, 0, 0.125);
--modal-content-border-radius: 0.5rem;
--modal-content-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);

/ Animations /
--modal-animation-duration: 200ms;
--modal-z-index: 1050;
}

/ Basic modal styles /
.modal {
position: fixed;
top: 0;
left: 0;
width: 100%;
min-height: 100%;
background-color: var(--modal-backdrop-bg);
z-index: var(--modal-z-index);
display: flex;
align-items: center;
justify-content: center;
opacity: 0;
transition: opacity var(--modal-animation-duration) ease-in-out;
backdrop-filter: blur(var(--modal-backdrop-blur));
}

.modal.in {
opacity: 1;
}

.modal-content {
background-color: var(--modal-content-bg);
border: var(--modal-content-border);
border-radius: var(--modal-content-border-radius);
box-shadow: var(--modal-content-shadow);
max-width: 500px;
width: 90%;
}

.modal-header {
display: flex;
justify-content: space-between;
align-items: center;
padding: 1rem;
border-bottom: 1px solid #dee2e6;
}

.modal-body {
padding: 1rem;
}

.modal-footer {
display: flex;
justify-content: flex-end;
gap: 0.5rem;
padding: 0.75rem;
border-top: 1px solid #dee2e6;
}

.close {
background: none;
border: none;
font-size: 1.5rem;
cursor: pointer;
padding: 0.25rem;
opacity: 0.5;
transition: opacity 0.15s ease-in-out;
}

.close:hover {
opacity: 0.75;
}
`

$3

For Bootstrap users, ngx-custom-modal works seamlessly with all Bootstrap versions:

`html





Bootstrap Modal

Left column content

Right column content

Close
Save changes


`

$3

`css
/ Dark mode support /
@media (prefers-color-scheme: dark) {
:root {
--modal-backdrop-bg: rgba(0, 0, 0, 0.8);
--modal-content-bg: #1f2937;
--modal-content-border: 1px solid #374151;
--modal-text-color: #f9fafb;
}
}

/ Reduced motion support /
@media (prefers-reduced-motion: reduce) {
:root {
--modal-animation-duration: 0ms;
}
}

/ High contrast mode /
@media (prefers-contrast: high) {
:root {
--modal-content-border: 2px solid currentColor;
--modal-backdrop-bg: rgba(0, 0, 0, 0.9);
}
}
`

🌍 Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Mobile browsers (iOS Safari, Chrome Mobile)

🛠️ Development

$3

- Node.js 18+
- Angular CLI 17+

$3

`bash
git clone https://github.com/AngelCareaga/ngx-custom-modal.git
cd ngx-custom-modal
npm install
`

$3

`bash
npm start
`

$3

`bash
npm run build:lib
`

$3

`bash
npm test
`

$3

This project uses Prettier for code formatting:

`bash
npm run format
`

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature`)
5. Open a Pull Request

$3

- Follow the existing code style
- Add tests for new features
- Update documentation for any API changes
- Use conventional commit messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

- angular-custom-modal - Created by Gerard Rovira Sánchez, which served as inspiration for this project
- Stephen Paul - For the initial Angular 2 Modal concept
- Angular Team - For the amazing framework

📞 Support

- 📧 Email: dev.angelcareaga@gmail.com
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 🌐 Website: angelcareaga.com

---