Default Passive Events is a lightweight JavaScript library that automatically applies passive event listeners for DOM events that typically don't require preventDefault() functionality. By automatically setting {passive: true} for touch, mouse, scroll, wheel, and animation events, it significantly improves scrolling performance and browser responsiveness.
npm install default-passive-eventsThe library operates as a side-effect import - simply importing/requiring it activates the passive event behavior globally:
import 'default-passive-events';For accessing utility functions:
import { eventListenerOptionsSupported } from 'default-passive-events/src/utils';For CommonJS:
require('default-passive-events');
const { eventListenerOptionsSupported } = require('default-passive-events/src/utils');For direct browser inclusion:
<script src="https://unpkg.com/default-passive-events"></script>import 'default-passive-events';
// After import, all supported event types are automatically made passive
document.addEventListener('mouseup', onMouseUp);
// → Internally called with {passive: true, capture: false}
document.addEventListener('scroll', onScroll);
// → Internally called with {passive: true, capture: false}
// Explicit passive: false is preserved
document.addEventListener('touchstart', onTouch, { passive: false });
// → Internally called with {passive: false, capture: false}
// Explicit capture settings are preserved
document.addEventListener('mousedown', onMouseDown, true);
// → Internally called with {passive: true, capture: true}Default Passive Events operates by:
EventTarget.prototype.addEventListener behaviorCore functionality that modifies addEventListener behavior to automatically apply {passive: true} for supported event types.
/**
* Side-effect import that modifies global addEventListener behavior
* No explicit exports - functionality is activated by importing
*/
import 'default-passive-events';Supported Event Types (25 total):
scroll, wheeltouchstart, touchmove, touchenter, touchend, touchleavemouseout, mouseleave, mouseup, mousedown, mousemove, mouseenter, mousewheel, mouseoverpointermove, pointerenter, pointerleave, pointerdown, pointerupanimationstart, animationend, animationiterationtransitionstart, transitionend, transitionrun, transitioncancelCustomize which events are made passive by setting the global configuration property before importing.
/**
* Global configuration property for customizing supported passive events
* Must be set before importing default-passive-events
*/
window.defaultPassiveEvents_supportedPassiveEvents: string[]Usage Examples:
// Configure custom passive events (set before import)
window.defaultPassiveEvents_supportedPassiveEvents = ['scroll', 'wheel', 'touchstart'];
import 'default-passive-events';
// Only scroll, wheel, and touchstart will be made passive
document.addEventListener('scroll', handler); // {passive: true}
document.addEventListener('mouseup', handler); // {passive: false} - not in custom listAccess to the original, unmodified addEventListener method when needed.
/**
* Access to original addEventListener method
* Available as _original property on any element's addEventListener
*/
element.addEventListener._original: (
type: string,
listener: EventListener | EventListenerObject,
options?: boolean | AddEventListenerOptions
) => void;Usage Examples:
import 'default-passive-events';
// Use original addEventListener when needed
document.addEventListener._original('mouseup', handler, { passive: false });
// Restore original behavior globally
EventTarget.prototype.addEventListener = document.addEventListener._original;Utility function for detecting EventListenerOptions support in the browser.
/**
* Detects if the browser supports EventListenerOptions (passive, capture, once)
* @returns {boolean} true if EventListenerOptions are supported, false otherwise
*/
function eventListenerOptionsSupported(): boolean;Usage Examples:
import { eventListenerOptionsSupported } from 'default-passive-events/src/utils';
if (eventListenerOptionsSupported()) {
// Browser supports passive event listeners
console.log('Passive events are supported');
} else {
// Fallback for older browsers
console.log('Passive events not supported');
}The enhanced addEventListener method that automatically applies passive defaults while preserving explicit options.
/**
* Enhanced addEventListener that automatically applies passive: true for supported events
* Preserves all original functionality while adding smart passive defaults
*/
EventTarget.prototype.addEventListener(
type: string,
listener: EventListener | EventListenerObject,
options?: boolean | AddEventListenerOptions
): void;Behavior Rules:
passive: true by default for supported event typespassive: false when specifieduseCapture and object options parametersaddEventListener signaturesUsage Examples:
import 'default-passive-events';
// Automatic passive application
document.addEventListener('scroll', handler);
// → {passive: true, capture: false}
// Explicit options preserved
document.addEventListener('touchstart', handler, { passive: false });
// → {passive: false, capture: false}
// Boolean useCapture handling
document.addEventListener('mouseup', handler, true);
// → {passive: true, capture: true}
// Mixed options
document.addEventListener('wheel', handler, { passive: false, capture: true });
// → {passive: false, capture: true}
// Unsupported events remain non-passive
document.addEventListener('click', handler);
// → {passive: false, capture: false}interface AddEventListenerOptions {
capture?: boolean;
once?: boolean;
passive?: boolean;
signal?: AbortSignal;
}
interface EventListener {
(evt: Event): void;
}
interface EventListenerObject {
handleEvent(object: Event): void;
}
interface EventTarget {
addEventListener(
type: string,
listener: EventListener | EventListenerObject | null,
options?: boolean | AddEventListenerOptions
): void;
removeEventListener(
type: string,
listener: EventListener | EventListenerObject | null,
options?: boolean | EventListenerOptions
): void;
}
interface EventListenerOptions {
capture?: boolean;
}