NgxOverlay Service

This service provides a convenient way to create and manage overlays (like modals, dropdowns, popovers, and tooltips) in your Angular application. It builds upon Angular CDK's Overlay module, adding simplified configuration and management.

Installation

npm install @ngxhelpers/overlay

Usage

1. Import NgxOverlay and inject it into your component:

   import { NgxOverlay } from '@ngxhelpers/overlay'; // Assuming you've published/imported the library
   
   constructor(private overlay: NgxOverlay) {}

2. Use the open method to create an overlay:

   const overlayRef = this.overlay.open({
   	component: MyComponent, // Or TemplateRef, HTMLElement, ElementRef
   	data: { message: 'Hello from overlay!' }, // Optional data
   	position: 'center', // Or 'topLeft', 'topRight', 'bottomLeft', 'bottomRight', 'dropdown', 'popover', or a custom PositionStrategy
   	origin: this.elementRef, // Optional origin element for positioning (important for 'dropdown' and 'popover')
   	options: {
   		hasBackdrop: true,
   		panelClass: ['my-overlay-class'], // Optional
   		backdropClass: ['my-backdrop-class'], // Optional
   		width: '300px' // Optional
   		// ... other NgxOverlayConfigOptions
   	}
   });
   
   // Access the component instance (if applicable)
   overlayRef.componentInstance?.myMethod();
   
   // Close the overlay programmatically
   overlayRef.close();
   
   // Subscribe to the afterClosed event (when the overlay closes)
   overlayRef.afterClosed.subscribe((result) => {
   	console.log('Overlay closed', result);
   });

API Reference

open<T, R = any>(params: NgxOverlayParams<T>): NgxOverlayRef<T, R>

Creates an overlay.

Parameters:

• params: NgxOverlayParams<T>: An object with the following properties:

  • component: Type<T> | TemplateRef<any> | HTMLElement | ElementRef: The component, template, or HTML element to display in the overlay.
  • data: any: (Optional) Data to pass to the overlay component or template (accessible via the NGX_OVERLAY_DATA injection token).
  • position: NgxDefaultOverlayPositions | PositionStrategy: The position of the overlay. Can be one of the predefined positions ('center', 'topLeft', etc.) or a custom PositionStrategy.
  • origin: ElementRef<HTMLElement> | HTMLElement: (Optional, required for 'dropdown' and 'popover' positions) The origin element for positioning the overlay.
  • options: NgxOverlayConfigOptions: (Optional) Additional options for configuring the overlay (see below).

dispose(disposeClass?: string): void

Destroys the overlay. Can destroy a specific overlay using its panel class or destroy all if no id is passed.

openHover<T, R = any>(params: NgxOverlayParams<T>): NgxOverlayRef<T, R>

Creates a hover overlay using similar parameters to the main open method. Intended for creating pop-up elements on mouse hover.

Parameters:

• params: NgxOverlayParams<T>: Same parameters as the open method.

disposeHover(data?: string): void

Closes a hover overlay. If no data is passed, disposes of all hover overlays. Useful for closing pop-up elements when the mouse pointer leaves a trigger element.

NgxOverlayConfigOptions

The options parameter in the open and openHover methods accepts an object of type NgxOverlayConfigOptions:

• hasBackdrop: boolean: Whether the overlay should have a backdrop. Defaults to false.
• panelClass: string | string[]: Custom CSS class(es) to apply to the overlay panel.
• backdropClass: string | string[]: Custom CSS class(es) to apply to the backdrop.
• width: string | number: Width of the overlay panel.
• height: string | number: Height of the overlay panel.
• minWidth: string | number: Minimum width of the overlay panel.
• minHeight: string | number: Minimum height of the overlay panel.
• maxWidth: string | number: Maximum width of the overlay panel.
• maxHeight: string | number: Maximum height of the overlay panel.
• boundBoxClass: string: Apply a class to the overlay bounding box element.
• disposeClass: string: A class to reference while closing or disposing a specific overlay. Defaults to ''.
• outsideClick: boolean: Closes overlay on outside click event. Defaults to false.
• closePrevious: boolean: Closes previously opened overlays or instances. Default is true.
• containerRef: ViewContainerRef: (Optional) If not set default set to global level viewref. Used for dynamically injecting content into specific areas of your application. Provide a ViewContainerRef to control where the overlay is rendered.
• content: any: (Optional) For using TemplateRef as a container.

NgxOverlayRef<T, R = any>

The open method returns an NgxOverlayRef object, which provides methods for interacting with the overlay:

• close(data?: R): void: Closes the overlay and optionally passes data back to the component that opened it.
• afterClosed: Subject<R | undefined>: An observable that emits when the overlay is closed, optionally with data passed from the close method.
• componentInstance: T | undefined: A reference to the component instance created inside the overlay (if applicable).
• origin?: ElementRef<HTMLElement> | HTMLElement | HTMLDivElement: Reference to origin element of overlay.

Predefined Positions (NgxDefaultOverlayPositions)

• 'center': Centers the overlay horizontally and vertically on the screen.
• 'topLeft': Positions the overlay at the top-left corner of the screen.
• 'topRight': Positions the overlay at the top-right corner of the screen.
• 'bottomLeft': Positions the overlay at the bottom-left corner of the screen.
• 'bottomRight': Positions the overlay at the bottom-right corner of the screen.
• 'dropdown': Positions the overlay below the origin element, like a dropdown. Requires the origin parameter.
• 'popover': Positions the overlay near the origin element, like a popover. Requires the origin parameter.

Custom Positioning

For more advanced positioning, you can create a custom PositionStrategy using the Angular CDK's Overlay module directly and pass it to the position parameter. Refer to the Angular CDK documentation for details on creating custom position strategies.