EventTarget: removeEventListener() method
Note:This feature is available inWeb Workers.
TheremoveEventListener()
method of theEventTarget
interface
removes an event listener previously registered withEventTarget.addEventListener()
from the target.
The event listener to be removed is identified using a combination of the event type,
the event listener function itself, and various optional options that may affect the matching process;
seeMatching event listeners for removal.
CallingremoveEventListener()
with arguments that do not identify any
currently registeredevent listeneron theEventTarget
has no
effect.
If anevent listeneris removed from anEventTarget
while another listener of the target is processing an event, it will not be triggered by the event. However, it can be reattached.
Warning:If a listener is registered twice, one with thecaptureflag set and one without, you must remove each one separately. Removal of a capturing listener does not affect a non-capturing version of the same listener, and vice versa.
Event listeners can also be removed by passing anAbortSignal
to anaddEventListener()
and then later callingabort()
on the controller owning the signal.
Syntax
removeEventListener(type,listener)
removeEventListener(type,listener,options)
removeEventListener(type,listener,useCapture)
Parameters
type
-
A string which specifies the type of event for which to remove an event listener.
listener
-
Theevent listenerfunction of the event handler to remove from the event target.
options
Optional-
An options object that specifies characteristics about the event listener.
The available options are:
capture
:A boolean value that specifies whether theevent listenerto be removed is registered as a capturing listener or not. If this parameter is absent, the default valuefalse
is assumed.
useCapture
Optional-
A boolean value that specifies whether theevent listenerto be removed is registered as a capturing listener or not. If this parameter is absent, the default value
false
is assumed.
Return value
None.
Matching event listeners for removal
Given an event listener previously added by calling
addEventListener()
,you may eventually
come to a point at which you need to remove it. Obviously, you need to specify the same
type
andlistener
parameters to
removeEventListener()
.But what about theoptions
oruseCapture
parameters?
WhileaddEventListener()
will let you add the same listener more than once
for the same type if the options are different, the only option
removeEventListener()
checks is the
capture
/useCapture
flag. Its value must
match forremoveEventListener()
to match, but the other values don't.
For example, consider this call toaddEventListener()
:
element.addEventListener("mousedown",handleMouseDown,true);
Now consider each of these two calls toremoveEventListener()
:
element.removeEventListener("mousedown",handleMouseDown,false);// Fails
element.removeEventListener("mousedown",handleMouseDown,true);// Succeeds
The first call fails because the value ofuseCapture
doesn't match. The
second succeeds, sinceuseCapture
matches up.
Now consider this:
element.addEventListener("mousedown",handleMouseDown,{passive:true});
Here, we specify anoptions
object in which
passive
is set totrue
,while the other options are left to
the default value offalse
.
Now look at each of these calls toremoveEventListener()
in turn. Any of
them in whichcapture
oruseCapture
is
true
fail; all others succeed.
Only thecapture
setting matters toremoveEventListener()
.
element.removeEventListener("mousedown",handleMouseDown,{passive:true});// Succeeds
element.removeEventListener("mousedown",handleMouseDown,{capture:false});// Succeeds
element.removeEventListener("mousedown",handleMouseDown,{capture:true});// Fails
element.removeEventListener("mousedown",handleMouseDown,{passive:false});// Succeeds
element.removeEventListener("mousedown",handleMouseDown,false);// Succeeds
element.removeEventListener("mousedown",handleMouseDown,true);// Fails
It's worth noting that some browser releases have been inconsistent on this, and unless
you have specific reasons otherwise, it's probably wise to use the same values used for
the call toaddEventListener()
when calling
removeEventListener()
.
Example
This example shows how to add amouseover
-based event listener that
removes aclick
-based event listener.
constbody=document.querySelector("body");
constclickTarget=document.getElementById("click-target");
constmouseOverTarget=document.getElementById("mouse-over-target");
lettoggle=false;
functionmakeBackgroundYellow(){
body.style.backgroundColor=toggle?"white":"yellow";
toggle=!toggle;
}
clickTarget.addEventListener("click",makeBackgroundYellow,false);
mouseOverTarget.addEventListener("mouseover",()=>{
clickTarget.removeEventListener("click",makeBackgroundYellow,false);
});
Specifications
Specification |
---|
DOM Standard #ref-for-dom-eventtarget-removeeventlistener② |
Browser compatibility
BCD tables only load in the browser