{"id":13808359,"url":"https://github.com/fidian/ngx-visibility","last_synced_at":"2025-04-10T20:31:45.874Z","repository":{"id":38724213,"uuid":"198287799","full_name":"fidian/ngx-visibility","owner":"fidian","description":"Angular module that detects when elements are visible. Uses IntersectionObserver.","archived":false,"fork":false,"pushed_at":"2024-12-23T21:15:55.000Z","size":1279,"stargazers_count":11,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-25T04:18:12.213Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/fidian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2019-07-22T19:17:27.000Z","updated_at":"2024-12-23T21:15:58.000Z","dependencies_parsed_at":"2024-05-08T19:46:29.088Z","dependency_job_id":"016c6f7c-371c-4cc9-881a-fe1b31ac9f03","html_url":"https://github.com/fidian/ngx-visibility","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidian%2Fngx-visibility","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidian%2Fngx-visibility/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidian%2Fngx-visibility/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidian%2Fngx-visibility/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fidian","download_url":"https://codeload.github.com/fidian/ngx-visibility/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248290040,"owners_count":21078923,"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":[],"created_at":"2024-08-04T01:01:40.898Z","updated_at":"2025-04-10T20:31:45.865Z","avatar_url":"https://github.com/fidian.png","language":"TypeScript","funding_links":[],"categories":["Third Party Components"],"sub_categories":["DOM"],"readme":"# NgxVisibility\n\nAngular 19.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.\n\nIf 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/).\n\nIf 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.\n\n\n## Demonstration\n\nThere's a [live demo](https://codesandbox.io/s/github/fidian/ngx-visibility-demo/tree/master/) over at CodeSandbox.io.\n\n\n## Installation\n\nInstall like other Angular libraries. First run a command to download the module.\n\n    npm install ngx-visibility\n\nNext, add the module to your project.\n\n    import { BrowserModule } from '@angular/platform-browser';\n    import { NgModule } from '@angular/core';\n    import { FormsModule } from '@angular/forms';\n\n    // Import the module\n    import { NgxVisibilityModule } from 'ngx-visibility';\n\n    import { AppComponent } from './app.component';\n\n    @NgModule({\n        declarations: [AppComponent, ItemComponent, NgxVisibilityDirective],\n\n        // Include the module.\n        imports: [BrowserModule, FormsModule, NgxVisibilityModule],\n        providers: [NgxVisibilityService],\n        bootstrap: [AppComponent]\n    })\n    export class AppModule {}\n\nFinally, you leverage the service directly or use some directives for common uses.\n\n\n## NgxVisibilityLazyLoadDirective\n\nLoad an image or a background image when the element is visible.\n\n    \u003cimg src=\"myImage.png\" ngxVisibilityLazyLoad /\u003e\n\n    \u003cimg srcset=\"myImage.png 1x, betterImage.png 2x\" ngxVisibilityLazyLoad /\u003e\n\n    \u003cdiv backgroundImage=\"myImage.png\" style=\"height: 100px; width: 82px\" ngxVisibilityLazyLoad\u003e\u003c/div\u003e\n\nSupports `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.\n\nConfiguration is allowed through `ngxVisibilityAnchorDirective`, `ngxVisibilityMargin` and `ngxVisibilityThreshold`, which are discussed below.\n\n\n## NgxVisibilityDirective\n\nEmit a boolean when an item becomes visible or is hidden from view.\n\n    \u003cmy-component (ngxVisibility)=\"updateVisibility($event)\"\u003e\u003c/my-component\u003e\n\nListener is automatically added and removed by the directive.\n\nConfiguration is allowed through `ngxVisibilityAnchorDirective`, `ngxVisibilityMargin` and `ngxVisibilityThreshold`, which are discussed below.\n\n\n## NgxVisibilityService\n\nThis service maintains the list of observers and calls callbacks when items become visible or are invisible.\n\n    import { Component, ElementRef, OnDestroy, OnInit } from '@angular/core';\n    import { NgxVisibilityService } from 'ngx-visibility';\n\n    @Component({\n        selector: 'my-component'\n    })\n    export class MyComponent implements OnDestroy, OnInit {\n        constructor(\n            private readonly ngxVisibilityService: NgxVisibilityService,\n            private readonly elementRef: ElementRef\n        ) {}\n\n        ngOnInit() {\n            this.ngxVisibilityService.observe(\n                // The native element reference\n                this.elementRef.nativeElement,\n\n                // A callback that is called whenever the element crosses\n                // a threshold. When you use thresholds, tracking how many\n                // have been crossed is up to you.\n                isVisible =\u003e {\n                    console.log('I am now', isVisible ? 'visible' : 'hidden');\n                },\n\n                // The configuration object is optional. Look at\n                // IntersectionObserver for what these values mean.\n                // The config is of type IntersectionObserverInit.\n                {\n                    // The viewport native element to use as our window.\n                    // Defaults to `window`.\n                    root: null,\n\n                    // How far outside the viewport to extend. Useful for\n                    // loading items that are almost going to be seen.\n                    // Negative margins will not load items until they\n                    // progress that far into the view window.\n                    // Must be specified in pixels or percent and use\n                    // the typical CSS margin formats.\n                    rootMargin: '40px',\n\n                    // Thresholds. Default is [ 0 ]. Can be either a number or\n                    // an array of thresholds. Values are from 0 (not visible)\n                    // to 1 (completely visible).\n                    threshold: [ 0, .33, .66 ]\n                }\n            );\n        }\n\n        ngOnDestroy() {\n            this.ngxVisibiltyService.unobserve(this.elementRef.nativeElement);\n        }\n    }\n\n\n## NgxVisibilityAnchorDirective\n\nUsed 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.\n\n    \u003cdiv ngxVisibilityAnchorDirective style=\"overflow: scroll; height: 40px; width: 40px\"\u003e\n        \u003cdiv *ngFor=\"let item in itemList\" ngxVisibility=\"setItemVisibility(item, $event)\"\u003e\n            {{ item.name }} is visible? {{ item.visibility }}\n        \u003c/div\u003e\n    \u003c/div\u003e\n\n\n## ngxVisibilityMargin\n\nThis 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.\n\n    \u003c!-- Load when it is within 100px of being seen. --\u003e\n    \u003cimg src=\"cool-image.png\" ngxVisibilityLazyLoad ngxVisibilityMargin=\"100px\" /\u003e\n\n    \u003c!-- Load if the element is within half of a screen away from being seen. --\u003e\n    \u003cdiv (ngxVisibility)=\"setVisibility($event)\" ngxVisibilityMargin=\"50%\" /\u003e\n\n\n## ngxVisibilityThreshold\n\nSets 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.\n\n    \u003cdiv ngxVisibility=\"setVisibility($event)\" ngxVisibilityThreshold=\"1\"\u003e...content...\u003c/div\u003e\n\n    \u003cdiv ngxVisibility=\"setVisibility($event)\" [ngxVisibilityThreshold]=\"[ 0, .5 ]\"\u003e...content...\u003c/div\u003e\n\n\n## License\n\nThis project is licensed under an [MIT license](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffidian%2Fngx-visibility","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffidian%2Fngx-visibility","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffidian%2Fngx-visibility/lists"}