This library uses event delegation to add debounced versions of native (and custom) bubbling DOM events.

• Why?
• Install
• Quick Start
• Usage
  • Leading / Trailing Debounce
  • Custom Events
  • Unregistering Events
  • Debounced Event Prefix
• API
• FAQ
• Releasing

Have you ever wired up event listeners for keyup, input, or mousemove? If so, you know that these events are dispatched frequently and often necessitate adding custom debounce functionality to your application.

What if you could simply listen for a debounced event instead? Now you can.

This technique pairs extremely well with libraries like Stimulus, TurboBoost Commands, and StimulusReflex. Here are some examples.

<input type="text" data-controller="example" data-action="debounced:input->example#work">
<input type="text" data-reflex="debounced:input->Example#work">

npm install debounced

Invoking initialize without arguments will register debounced events for all native DOM events that bubble.

import debounced from 'debounced'

// initialize without args to register all native DOM events that bubble
debounced.initialize()

You can also initialize with a custom list of events.

// initialize with a custom list of events
debounced.initialize(['click', 'input', 'keydown'])

// listen for debounced events
document.addEventListener('debounced:input', event => { ... })
document.getElementById('example').addEventListener('debounced:keydown', event => { ... })
document.querySelectorAll('a').forEach(a => {
  a.addEventListener('debounced:click', event => { ... })
})

Initialize with custom options.

debounced.initialize(debounced.defaultEventNames, { wait: 500, leading: true, trailing: false })

You can register additional events at any time.

// register more events after initialization
debounced.register(['change', 'mousedown'])

You can customize options for registered events by re-registering with different options.

// re-register events and to change options
debounced.register(debounced.registeredEventNames, { wait: 100 })

You can specify when debounced events fire via the leading and trailing options.

• leading - fires after the source event but before waiting
• trailing - fires after the source event and after waiting

Leading and trailing events will only fire once per source event.

You can add debounced versions of custom events.

// register an individual custom event
debounced.registerEvent('custom-event', { ... })

// register a list of custom events
debounced.register(['custom-event-one', 'custom-event-two'], { wait: 150 })

You can unregiser events at any time.

// unregister a single event
debounced.unregisterEvent('keyup')

// unregister a list of events
debounced.unregister(['click', 'input', 'keydown'])

// unregister all events
debounced.unregister(debounced.registeredEventNames)

You can change the prefix of the debounced event names.

debounced.prefix = 'custom-prefix' // must be set before invoking initialize
debounced.initialize()
document.addEventListener('custom-prefix:click', event => { ... })

The source is small and well documented. Learn more about the API here.

Q: What are the default native events that bubble?

A: View the list here and learn more about these events at MDN.

Q: Can I register an event more than once?

A: Yes, event re-registration overwrites any existing registrations.

Q: Do I have to specify all options when registering an event?

A: No, any omitted options will apply the defaults.

Q: Are importmaps supported?

A: Yes, this library is compatible with importmaps.

1. Run npm update to pick up the latest dependencies
2. Update the version at package.json - pre-release versions use -preN
3. Run npm run standardize
4. Run npm run build
5. Commit and push any changes to GitHub
6. Run npm publish --access public
7. Create a new release on GitHub (here)