README.md

---

---

Attention! This repository is archived and the library has been moved to tinkoff/ng-web-apis monorepository

---

---

Intersection Observer API for Angular

Part of Web APIs for Angular

This is a library for declarative use of Intersection Observer API with Angular.

Install

If you do not have @ng-web-apis/common:

npm i @ng-web-apis/common

Now install the package:

npm i @ng-web-apis/intersection-observer

Usage

1. Import IntersectionObserverModule for directives to work

2. Create IntersectionObserver with waIntersectionObserver directive

3. Observe elements with waIntersectionObservee directive

4. Optional: provide root element with waIntersectionRoot directive and use waIntersectionThreshold and waIntersectionRootMargin attributes to configure IntersectionObserver options

   NOTE: Keep in mind these are used one time in constructor so you cannot use binding, only strings. Pass comma separated numbers to set an array of thresholds.

Usage with Jest

DOM environment provided by Jest does not emulate IntersectionObserver API and need to be mocked. You can add the following line to your setup.ts:

// setup.ts
import '@ng-web-apis/universal/mocks';

to use mocks from @ng-web-apis/universal package.

Examples

Observing multiple elements intersecting with viewport using single observer

<section waIntersectionObserver waIntersectionThreshold="0.5">
    <div (waIntersectionObservee)="onIntersection($event)">
        I'm being observed
    </div>
    <div (waIntersectionObservee)="onIntersection($event)">
        I'm being observed
    </div>
</section>

Observing elements intersecting with parent element, each having different configuration therefore using individual observers:

<section waIntersectionRoot>
    <div
        waIntersectionObserver
        waIntersectionThreshold="0.5"
        (waIntersectionObservee)="onIntersection($event)"
    >
        I'm being observed
    </div>
    <div
        waIntersectionObserver
        waIntersectionThreshold="1,0.5,0"
        (waIntersectionObservee)="onIntersection($event)"
    >
        I'm being observed
    </div>
</section>

Services

Alternatively you can use Observable-based services:

1. IntersectionObserveeService can be used to observe elements under waIntersectionObserver directive in the DI tree

2. IntersectionObserverService can be used to observe single element independently. Provide tokens manually to configure it:

@Component({
    selector: 'my-component',
    providers: [
        IntersectionObserverService,
        {
            provide: INTERSECTION_THRESHOLD,
            useValue: 0.5,
        },
        {
            provide: INTERSECTION_ROOT_MARGIN,
            useValue: '10px',
        },
    ],
})
export class MyComponent {
    constructor(
        @Inject(IntersectionObserverService) entries$: IntersectionObserverService,
    ) {
        entries$.subscribe(entries => {
            // Don't forget to unsubscribe
            console.log(entries);
        });
    }
}

In this case provide INTERSECTION_ROOT up the DI tree if you want to observe intersection with a particular parent element

Browser support

15+	55+	51+	12.2+

You can use polyfill to support older browsers

Angular Universal

If you want to use this package with SSR, you need to mock IntersectionObserver class on the server. You can use our Universal package for this, see this example.

Demo

You can try online demo here

See also

Other Web APIs for Angular by @ng-web-apis

Open-source

Do you also want to open-source something, but hate the collateral work? Check out this Angular Open-source Library Starter we’ve created for our projects. It got you covered on continuous integration, pre-commit checks, linting, versioning + changelog, code coverage and all that jazz.