Event Utilities

Event handling utilities for detecting and configuring passive event listeners to improve scroll performance.

Capabilities

Passive Event Listener Detection

Determine whether the current browser supports passive event listeners and return appropriate options.

/**
 * Determine whether the current browser supports passive event listeners, and if so, use them
 * @param globalObj - The global window object to test against (defaults to window)
 * @returns {passive: true} if passive listeners are supported, false otherwise
 */
function applyPassive(globalObj?: Window): boolean | EventListenerOptions;

Usage Examples:

import { applyPassive } from '@material/dom/events';

// Apply passive listeners for scroll events
const passiveOptions = applyPassive();
element.addEventListener('touchstart', handler, passiveOptions);
element.addEventListener('touchmove', handler, passiveOptions);
element.addEventListener('wheel', handler, passiveOptions);

// Use with custom window object (for testing or iframe contexts)
const iframeWindow = iframe.contentWindow;
const iframePassiveOptions = applyPassive(iframeWindow);
iframeElement.addEventListener('scroll', handler, iframePassiveOptions);

Passive Event Listeners

Passive event listeners are a web standard that improves scrolling performance by telling the browser that the event handler will not call preventDefault(). This allows the browser to process scrolling immediately without waiting for JavaScript execution.

Benefits

• Improved scroll performance: Browser can start scrolling immediately
• Better user experience: Reduces jank and improves responsiveness
• Battery life: Less CPU usage on mobile devices
• Backward compatibility: Gracefully falls back to standard listeners

When to Use

Use passive listeners for events where you:

• Monitor scrolling or touch events
• Don't need to prevent default behavior
• Want optimal performance (especially on mobile)

Common events that benefit from passive listeners:

• touchstart
• touchmove
• wheel
• scroll

Browser Support

The function automatically detects support for passive listeners and returns:

• {passive: true} - Modern browsers with passive listener support
• false - Older browsers that don't support passive listeners

This ensures your code works consistently across all browsers while taking advantage of performance improvements when available.