Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/fidian/ngx-visibility

Angular module that detects when elements are visible. Uses IntersectionObserver.
https://github.com/fidian/ngx-visibility

Last synced: 2 days ago
JSON representation

Angular module that detects when elements are visible. Uses IntersectionObserver.

Awesome Lists containing this project

README 

        
# NgxVisibility



Angular 18.x library to monitor when elements are visible in the DOM. When you have a huge list of components, this is more performant than other libraries because it keeps the number of observers to a minimum. It uses IntersectionObserver to do the work.



If you only care about when elements are resized, including resize events due to browser window size changing, look at [ngx-resize-observer](https://github.com/fidian/ngx-resize-observer/).



If you want to be notified when DOM elements change properties, [ngx-mutation-observer](https://github.com/fidian/ngx-mutation-observer/) would be a good pick.



## Demonstration



There's a [live demo](https://codesandbox.io/s/github/fidian/ngx-visibility-demo/tree/master/) over at CodeSandbox.io.



## Installation



Install like other Angular libraries. First run a command to download the module.



    npm install ngx-visibility



Next, add the module to your project.



    import { BrowserModule } from '@angular/platform-browser';

    import { NgModule } from '@angular/core';

    import { FormsModule } from '@angular/forms';



    // Import the module

    import { NgxVisibilityModule } from 'ngx-visibility';



    import { AppComponent } from './app.component';



    @NgModule({

        declarations: [AppComponent, ItemComponent, NgxVisibilityDirective],



        // Include the module.

        imports: [BrowserModule, FormsModule, NgxVisibilityModule],

        providers: [NgxVisibilityService],

        bootstrap: [AppComponent]

    })

    export class AppModule {}



Finally, you leverage the service directly or use some directives for common uses.



## NgxVisibilityLazyLoadDirective



Load an image or a background image when the element is visible.



    



    



    



Supports `src` and `srcset` for images, `backgroundImage` for all HTML elements. It's highly recommended that you set at least a placeholder size (possibly with `min-height` and `min-width`) for elements. Once the item is flagged visible, the observer is removed and the item stays visible.



Configuration is allowed through `ngxVisibilityAnchorDirective`, `ngxVisibilityMargin` and `ngxVisibilityThreshold`, which are discussed below.



## NgxVisibilityDirective



Emit a boolean when an item becomes visible or is hidden from view.



    



Listener is automatically added and removed by the directive.



Configuration is allowed through `ngxVisibilityAnchorDirective`, `ngxVisibilityMargin` and `ngxVisibilityThreshold`, which are discussed below.



## NgxVisibilityService



This service maintains the list of observers and calls callbacks when items become visible or are invisible.



    import { Component, ElementRef, OnDestroy, OnInit } from '@angular/core';

    import { NgxVisibilityService } from 'ngx-visibility';



    @Component({

        selector: 'my-component'

    })

    export class MyComponent implements OnDestroy, OnInit {

        constructor(

            private readonly ngxVisibilityService: NgxVisibilityService,

            private readonly elementRef: ElementRef

        ) {}



        ngOnInit() {

            this.ngxVisibilityService.observe(

                // The native element reference

                this.elementRef.nativeElement,



                // A callback that is called whenever the element crosses

                // a threshold. When you use thresholds, tracking how many

                // have been crossed is up to you.

                isVisible => {

                    console.log('I am now', isVisible ? 'visible' : 'hidden');

                },



                // The configuration object is optional. Look at

                // IntersectionObserver for what these values mean.

                // The config is of type IntersectionObserverInit.

                {

                    // The viewport native element to use as our window.

                    // Defaults to `window`.

                    root: null,



                    // How far outside the viewport to extend. Useful for

                    // loading items that are almost going to be seen.

                    // Negative margins will not load items until they

                    // progress that far into the view window.

                    // Must be specified in pixels or percent and use

                    // the typical CSS margin formats.

                    rootMargin: '40px',



                    // Thresholds. Default is [ 0 ]. Can be either a number or

                    // an array of thresholds. Values are from 0 (not visible)

                    // to 1 (completely visible).

                    threshold: [ 0, .33, .66 ]

                }

            );

        }



        ngOnDestroy() {

            this.ngxVisibiltyService.unobserve(this.elementRef.nativeElement);

        }

    }



## NgxVisibilityAnchorDirective



Used to flag a viewport instead of using the whole window. When using this directive, the component must also use the `ngxVisibility` or `ngxVisibilityLazyLoad` directive, otherwise this directive has no effect. Really, that's not too bad but it is a little wasteful because resources will be loading before you want them.



    


        


            {{ item.name }} is visible? {{ item.visibility }}

        


    



## ngxVisibilityMargin



This attribute is used with `ngxVisibility` or `ngxVisibilityLazyLoad` in order to set the margin when observing that element. Margins are specified as per the CSS properties and must be measured in pixels or percent.



    

    



    

    



## ngxVisibilityThreshold



Sets up one or more thresholds when combined with `ngxVisibility` or `ngxVisibilityLazyLoad`. It accepts an array, a number, or a string that will be converted to a number. Numbers need to be within the range of 0 to 1.



    
...content...



    
...content...



## License



This project is licensed under an [MIT license](LICENSE.md).