CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-default-passive-events

Makes {passive: true} by default when EventListenerOptions are supported

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

Default Passive Events

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.

Package Information

  • Package Name: default-passive-events
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install default-passive-events

Core Imports

The 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>

Basic Usage

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}

Architecture

Default Passive Events operates by:

  • Feature Detection: Automatically detects EventListenerOptions support
  • Global Override: Replaces EventTarget.prototype.addEventListener behavior
  • Smart Defaults: Applies passive: true only for supported event types
  • Configuration: Allows customization via global window property
  • Fallback: Gracefully degrades on unsupported browsers

Capabilities

Automatic Passive Event Handling

Core 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 Events: scroll, wheel
  • Touch Events: touchstart, touchmove, touchenter, touchend, touchleave
  • Mouse Events: mouseout, mouseleave, mouseup, mousedown, mousemove, mouseenter, mousewheel, mouseover
  • Pointer Events: pointermove, pointerenter, pointerleave, pointerdown, pointerup
  • Animation Events: animationstart, animationend, animationiteration
  • Transition Events: transitionstart, transitionend, transitionrun, transitioncancel

Configuration

Customize 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 list

Original addEventListener Access

Access 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;

Feature Detection

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');
}

Modified addEventListener Behavior

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:

  • Sets passive: true by default for supported event types
  • Preserves explicit passive: false when specified
  • Handles both boolean useCapture and object options parameters
  • Maintains compatibility with all original addEventListener signatures
  • Only activates when EventListenerOptions are supported by the browser

Usage 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}

Types

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;
}

Browser Compatibility

  • Modern Browsers: Full functionality with EventListenerOptions support
  • Legacy Browsers: Graceful fallback (no modification of addEventListener)
  • Detection: Automatic feature detection using property descriptor test
  • No Dependencies: Zero runtime dependencies, works in all JavaScript environments

Install with Tessl CLI

npx tessl i tessl/npm-default-passive-events
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/default-passive-events@4.0.x
Publish Source
CLI
Badge
tessl/npm-default-passive-events badge