jquery-events-to-dom-events

1.1.0 verified Fri May 01 auth: no javascript

A tiny zero-dependency library (30 LOC) that bridges jQuery custom events to DOM CustomEvents, enabling vanilla JS listeners for jQuery-triggered events. Version 1.1.0, maintained but low release cadence. Key differentiator: works without refactoring existing jQuery code, designed for StimulusJS and Turbolinks, bidirectional (also forwards DOM events to jQuery). Requires jQuery loaded globally as window.$.

Common errors

error Uncaught TypeError: Cannot read properties of null (reading 'split') ↓

cause jQuery is not loaded or window.$ is undefined when delegate is called.

fix

Ensure jQuery is loaded and available as window.$ before using this library.

error document.addEventListener('my.custom.event', handler) not firing ↓

cause DOM event names must be prefixed with '$'.

fix

Use document.addEventListener('$my.custom.event', handler) instead.

error Cannot find module 'jquery-events-to-dom-events' when using require() ↓

cause Library is ESM-only, not compatible with CommonJS require().

fix

Use import syntax: import { delegate } from 'jquery-events-to-dom-events'

Warnings

gotcha Requires jQuery to be available globally as window.$. If not set, library fails silently. ↓

fix Ensure jQuery is loaded and assigned to window.$ before importing the library.

gotcha DOM event names are prefixed with a dollar sign ($). Forgetting the prefix causes the listener to never fire. ↓

fix Always prepend '$' to the jQuery event name when using addEventListener.

gotcha Only works with custom jQuery events triggered via $.trigger, not native browser events (e.g., 'click'). ↓

fix Use only for jQuery custom events (e.g., 'hidden.bs.modal'). For native events, attach listeners directly.

gotcha Library does not clean up event listeners unless undel is called. Delegation persists across page navigations (e.g., Turbolinks). ↓

fix Call undel() when the component disconnects (e.g., in Stimulus disconnect or useEffect cleanup).

Install

npm install jquery-events-to-dom-events

yarn add jquery-events-to-dom-events

pnpm add jquery-events-to-dom-events

Imports

delegate

wrong

const delegate = require('jquery-events-to-dom-events').delegate

correct

import { delegate } from 'jquery-events-to-dom-events'

ESM-only; using require might not work depending on bundler configuration.

undel

wrong

import { undelegate } from 'jquery-events-to-dom-events'

correct

import { undel } from 'jquery-events-to-dom-events'

The library exports 'undel', not 'undelegate'.

default

wrong

import jqueryEventsToDomEvents from 'jquery-events-to-dom-events'

correct

import * as jqueryEventsToDomEvents from 'jquery-events-to-dom-events'

No default export; use namespace import.

Quickstart

Shows how to delegate a jQuery event to a DOM CustomEvent and listen for it.

import { delegate, undel } from 'jquery-events-to-dom-events';
// Set up event delegation for a jQuery custom event
delegate('my.custom.event');
// Listen for the DOM version (prefixed with $)
document.addEventListener('$my.custom.event', (e) => {
  console.log('Received:', e.detail);
});
// Later, to stop delegation:
// undel('my.custom.event');
// If jQuery is not already global, ensure it is:
// window.$ = window.jQuery = require('jquery');