@taiga-ui/event-plugins NPM

Angular Event Plugins

@taiga-ui/event-plugins is a tiny (1KB gzip) library for optimizing change detection cycles for performance sensitive events (such as touchmove, scroll, drag etc.) and declarative preventDefault() and stopPropagation().

How to use

Add NG_EVENT_PLUGINS to your app providers:

bootstrapApplication(AppComponent, {
  providers: [NG_EVENT_PLUGINS],
});

Use new modifiers for events in templates and in @HostListener:

.stop to call stopPropagation() on event
.prevent to call preventDefault() on event
.self to skip bubbled events
.zoneless to call event handler outside Angular's NgZone
.capture to listen to events in capture phase
.passive to add passive event listener
.once to remove event listener after first callback
resize to watch for elements changing dimensions with ResizeObserver
.debounce~<delay> to delay the execution of the event handler for a specified time (ms or s)
.throttle~<delay> to limits how often the event handler can run for a specified time (ms or s)

For example:

<div (mousedown.prevent)="onMouseDown()">Clicking on this DIV will not move focus</div>

<div (click.stop)="onClick()">Clicks on this DIV will not bubble up</div>

<div (mousemove.zoneless)="onMouseMove()">Callbacks to mousemove will not trigger change detection</div>

<div (click.capture.stop)="onClick()">
  <div (click)="never()">Clicks will be stopped before reaching this DIV</div>
</div>

<button (click.debounce~300ms)="onClick()">Debounced Click</button>
<button (click.debounce~2s)="onClick()">Debounced Click</button>

<button (click.throttle~300ms)="onClick()">Throttled Click</button>
<button (click.throttle~2s)="onClick()">Throttled Click</button>

You can also re-enter NgZone and trigger change detection, using @shouldCall decorator that takes a predicate function as argument:

<div (scroll.zoneless)="onScroll($event.currentTarget)">
  Scrolling this DIV will only trigger change detection and onScroll callback if it is scrolled to bottom
</div>

import {shouldCall} from '@taiga-ui/event-plugins';

export function scrollFilter({
 scrollTop, scrollHeight, clientHeight
}: HTMLElement): boolean {
    return scrollTop === scrollHeight - clientHeight;
}

// ...

@shouldCall(scrollFilter)
onScroll(_element: HTMLElement): void {
    this.someService.requestMoreData();
}

Angular global events only support body, window and document. You can listen to events on any global object with these plugins by replacing : with > symbol, for example:

@HostListener('visualViewport>resize', ['$event.target'])
onPinchZoom({ scale }: VisualViewport) {
    console.log(scale)
}

iOS currently doesn't support the contextmenu event. Instead, you can use a custom longtap event. This event captures the contextmenu event on non-iOS devices and simulates similar behavior on iOS devices.

<div (longtap)="showContextMenu($event.detail.clientX, $event.detail.clientY)">Div with context menu</div>

All examples above work the same when used with @HostListener and CustomEvent

Important notes

Predicate is called with the same arguments as the decorated method and in the context of class instance (has access to this)
Decorated method will be called and change detection triggered if predicate returns true.
.zoneless modifier will not work with built-in keyboard pseudo-events, such as keydown.enter or keydown.arrowDown since Angular re-enters NgZone inside internal handlers.

Demo

You can try this interactive demo

You can also read this detailed article explaining how this library works

Maintained

@taiga-ui/event-plugins is a part of Taiga UI libraries family which is backed and used by a large enterprise. This means you can rely on timely support and continuous development.

License

🆓 Feel free to use our library in your commercial and private applications

All @taiga-ui/event-plugins packages are covered by Apache 2.0