Event Listener Register
Add event listeners with name and remove them by name in native JavaScript.
This module is intended for a support tool to rewrite jQuery dependent programs in native JavaScript.
The module provides wrapper functions for EventTarget.addEventListener()
and removeEventListener()
that allow users to manage event listeners by name and handle multiple listeners in a single call.
Usage
For Node.js, install the package using npm
npm install --save event-listener-register
and import the functions.
; // or import as CommonJS moduleconst addListener removeListener getListeners = ;
For browser, load the package from CDN and expose the functions.
Then, use the functions…
To add listener:
// add a listener; // add a listener for capture phase;; // add a listener to multiple event types;; // add a listener using name as type suffix;;; // add a listener without name;; // add multiple listeners// with array; // with object// - listeners for capture phase are not supprted;
To remove listener:
// remove all listeners; // remove all listeners added to an event type; // remove all listeners with a name (regardless of the type);; // remove a listener; // remove a listener using name as type suffix; // remove a listener without name;; // remove multiple listeners// with space-separated types/names;;; // with array; // with object// - listeners for capture phase without name are not supprted// - falsy values indicate removal of all listeners matching the types/names;
To retrieve listeners:
// retrieve all listeners; // retrieve listeners with name; // retrieve listeners for a event type; // retrieve listeners with function;;
API
addListener(target, type, listener[, options][, name]])
addListener(target, listeners)
Adds one or multiple event listeners to an event target.
The first form is to add a single event listener to one or multiple event types.
Event listeners can be named by passing the name to the name
argument or adding it to a event type as a suffix.
While listener name as argument is applied to all event types in the type
argument, the one as suffix is only applied to the type it is added. It also has higher priority than the one as argument.
The second form is to add multiple listeners. listeners
can be either an array or an object.
When using object, listener names have to be provided as type suffix and listeners for capture phase are not supproted.
Parameters:
-
target [EventTarget]
Event target to add listener -
type [String]
One or more space-separated event types to listen for
Each type can have a suffix used for listener name. -
listener [Function]
Event listener function -
options [Object|Boolean] (optional)
Option value(s) used for theoptions
/useCapture
argument ofaddEventListener()
call -
name [String] (optional)
Name for the listener
Whentype
has suffix, this value is overridden by it. -
listeners [Array|Object]
– Array of parameters for each listener
[ [ type , listener [, options ] [, name ] ] , ... ]
– Object in which the keys are types and the values are listener functions
{ type : listener , ... }
removeListener(target[, type[, listener[, options]]])
removeListener(target, listeners)
Remove one or multiple event listeners from an event target.
The first form is to remove a single event listener, all event listeners or event listeners for certain event types or listener names.
The listener to remove can be specified by name or reference to the listener function. When a listener name is passed to the listener
argument, the options
argument is completely ignored. In contrast, omitting options
works as a shorthand for specifying {capture: false}
when passing a listener function.
If the listener to remove is not specified, all event listeners listening for the specified event type(s) will be removed.
Removing event listeners across the types can be done by passing an empty string to the type
argument. You can specify the listeners by name or by function in this case, too. To specifying listeners by name, you can also pass the listener name preceded by .
to the type
argument. (a type starting with .
is treated as an empty type + suffix)
If neither types nor listeners are specified, all event listeners added to the event target will be removed.
The second form is to remove multiple listeners. listeners
can be either an array or an object.
When using object, listeners for capture phase without name are not supproted. And you can use any falsy value to omit specifying a listener name/function.
Parameters:
-
target [EventTarget]
Event target to remove listener -
type [String] (optional)
One or more space-separated event type listening for
Each type can have a suffix used for listener name.
If the value is empty, the function retrieves the listeners to remove ignoring the type.
If a type starts with.
, the function takes it as en empty type with suffix.
When this parameter is omitted, the function removes all listeners added to the target. -
listener [Function|String] (optional)
Event listener function or the listener name used to add the listener
When a string is passed andtype
has suffix, this value is overridden by the suffix.
When this parameter is omitted, the function removes all listeners lietening for the event type. -
options [Object|Boolean] (optional)
Option value(s) used for theoptions
/useCapture
argument ofremoveEventListener()
call
When a string is passed tolistener
, this parameter is ignored. -
listeners [Array|Object]
– Array of parameters for each listener or types to remove all listeners
[ [ type [, listener [, options ] ] ] | type , ... ]
– Object in which the keys are types and the values are listener names or functions
{ type : listener , ... }
getListeners(target[, criteria])
Retrieve the event listeners added to an event target.
Parameters:
-
target [EventTarget]
Event target to retrieve listeners -
criteria [Object] (optional)
Criteria to narrow the result
Properties:name
- [String] - Listener nametype
- [String] - Event typefn
- [Function] - Listener functioncapture
- [Boolean] - Phase of event the search for the listeners to be made
Iftrue
, only listeners for capture phase are retrieved. Iffalse
, only listeners for bubble phase are retrieved.
Return value:
- [Array]
Registration objects (parameters used onaddListener()
call) of the event listeners that meet the criteria.
Properties:name
- [String] - Listener nametype
- [String] - Event typefn
- [Function] - Listener functionoptions
- [Object|Boolean] - Value foroptions
/useCapture