Events API

evt.add()

async

Adds an event listener that calls a specified function whenever the event is dispatched to the target.

  • An event listener can be attached to a Window, Document, Element, array of elements, NodeList, or HTMLCollection.
    If no target is specified, automatically detects the correct target.
  • Accepts a type of event to listen for, provided as a case-sensitive string, as the first argument.
    Accepts a function (or an object with a handleEvent method) that will be called when the specified event occurs, as the second argument.
    Accepts an optional third argument, which can be one of the following:
    Argument
    Description
    true
    The handler will be invoked during the capture phase (before the event reaches its target).
    false
    The handler will be invoked during the bubbling phase (after the event has passed through the capture phase).
    This is the default value.
    null
    The handler will be executed before the default action for the specified event is performed.
    object
    An object that defines the characteristics of an event listener, including the following options:
    Option
    Type
    Default
    Description
    capture
    boolean
    false
    Specifies whether the handler is invoked during the capture phase (true) or the bubbling phase (false).
    once
    boolean
    false
    Specifies that the listener will be called at most once after being added and automatically removed after the first call, if set to true.
    passive
    boolean
    false
    Specifies that the listener's function will never call preventDefault(), if set to true.
    signal
    AbortSignal
    none
    Allows the handler to be removed using abort().
    The event types "visible" and "invisible" include the following options:
    Option
    Type
    Default
    Description
    root
    DOM element
    null
    The element used as the viewport for observing intersections. Defaults to the browser viewport if set to null.
    rootMargin
    string
    0px 0px 0px 0px
    Margins around the root (in CSS syntax). Expands or shrinks the effective viewport for intersection calculations.
    threshold
    number
    array
    0
    A single number or array of numbers (0 to 1) indicating at what percentage of the target's visibility the observer's callback should be triggered.
    The event type "mutation" includes the following options:
    Option
    Type
    Default
    Description
    subtree
    boolean
    true
    Set to true to enable monitoring of the entire subtree of nodes rooted at the target.
    All properties will apply to the entire subtree rather than just the target node.
    Changes in a descendant subtree will still be observed even after the descendant is removed, until the removal notification is delivered.
    childList
    boolean
    true
    Set to true to monitor the target node (and its descendants, if subtree is true) for added or removed child nodes.
    attributes
    boolean
    true
    Set to true to monitor attribute value changes on the observed nodes.
    attributeFilter
    array
    none
    An array of attribute names to monitor, if omitted, all attribute changes trigger notifications.
    attributeOldValue
    boolean
    true
    Set to true to capture the previous value of any changing attribute while monitoring for attribute changes on nodes.
    characterData
    boolean
    true
    Set to true to monitor the target node (and its descendants, if subtree is true) for changes to its character data.
    characterDataOldValue
    boolean
    true
    Set to true to capture the previous text value whenever it changes on monitored nodes.
    All options are optional.
  • The event handler receives a standard event object with the following additional properties:
    Property
    Type
    Description
    it
    DOM element
    The element the event was assigned to.
    While "target" points to the specific element that triggered the event, "it" references the assigned element.
    If an event is bound to a <div> and triggered on a child <span>, "target" will be <span>, and "it" will be <div>.
    itType
    string
    The actual type of the event.
    For example, for a "click-out" event, the "type" property will be "click", while the "itType" property will represent "click-out".
    For the "submit" event, the event handler additionally receives a "form" property, which holds the form data as an object.
  • It is not necessary to wait for the method to be executed using await if not needed.
Example: 
// Adds an event listener to the Document.
document.evt.add('click', (e) => {});

// Adds an event listener to the Window.
window.evt.add('scroll', (e) => {});

// Adds an event listener to the <div> element.
$('div').evt.add('click', (e) => {});

// Adds an event listener to all <div> elements.
$('div ?').evt.add('click', (e) => {});

// Automatically detects the correct target and adds an event listener to it, in this case, the Document.
evt.add('click', (e) => {});

// Automatically detects the correct target and adds an event listener to it, in this case, the Window.
evt.add('scroll', (e) => {});

// The event handler is invoked during the capture phase.
evt.add('click', (e) => {}, true);
evt.add('click', (e) => {}, {capture: true});

// Adds an event listener with the specified options to the <div> element.
$('div').evt.add('click', (e) => {}, {
   capture: false,
   once: true,
   passive: false
});

// Adds a mutation event listener to all elements.
evt.add('mutation', (e) => {}, {
   childList: true,
   attributes: true,
   characterData: true,
   subtree: true,
   attributeOldValue: true,
   characterDataOldValue: true
});

// Adds a mutation event listener to a <div> element.
$('div').evt.add('mutation', (e) => {});

// Adds a resize event listener to the window object.
evt.add('resize', (e) => {});

// Adds a resize event listener to a <div> element.
$('div').evt.add('resize', (e) => {});

// The event handler is triggered whenever the <div> element becomes visible within the viewport.
$('div').evt.add('visible', (e) => {}, {
   root: null,
   rootMargin: '0px 0px 0px 0px',
   threshold: 0
});

// The event handler is triggered whenever the <div> element becomes invisible within the viewport.
$('div').evt.add('invisible', (e) => {});

// Waits for the event listener to be added to the target.
await evt.add('click', (e) => {});
Previous Overview Next evt.remove()