Liev

Listen to events – A simple, small, and performant utility for listening to and attaching native and custom DOM events.

Why should You use Liev?

• Liev attaches events internally to a parent element (document.documentElement per default), so you don't need to attach new event listeners when new HTMLElements's get added to the DOM.
• Liev attaches as little event listeners as possible by using event delegation to make your web app more performant (You can read about that idea here).
• Liev decides whether you're listener should be passive or not, so You don't have to think about it (Liev can not look into nested functions, so sometimes you have to set it to false when you call Event.preventDefault()).

Installation

Using Node:

npm i liev

Using a script tag:

Look in the dist folder for the build files and more information.

API

Table of Contents

• EventHandler
  • Parameters
• on
  • Parameters
• off
  • Parameters
• emit
  • Parameters

EventHandler

Type: Function

Parameters

• target HTMLElement The element that triggered the event
• event Event An object based on Event describing the event that has occurred

on

Adds a listener

Parameters

• type String A case-sensitive string representing the event type to listen for

• selector String A string containing one or more selectors to match, use an empty string to match everything

• callback EventHandler A function that gets executed when an event of the specified type occurs

• options Object (optional, default {})

  • options.once Boolean whether a listener should only be executed once or not (optional, default false)
  • options.element HTMLElement the parent element to that the listener is attached (optional, default document.documentElement)
  • options.passive Boolean? Whether a listener should be passive or not, looks per default into a stringified version of your callback to decide based on your code if it should be passive or not

Returns Boolean true if added, false if done nothing

off

Removes a listener that was added through the "on" method

Parameters

• type String The type that was used on the "on" method

• selector String The selector that was used on the "on" method

• callback EventHandler The function that was used on the "on" method

• options Object (optional, default {})

  • options.once Boolean The value that was used on the "on" method (optional, default false)
  • options.element HTMLElement The element that was used on the "on" method (optional, default document.documentElement)
  • options.passive Boolean? The value that was used on the "on" method

Returns Boolean true if removed, false if done nothing

emit

Emits an event from an element

Parameters

• event String A case-sensitive string representing the event type to emit (can, or ideally should be, a custom one)
• element HTMLElement The element from that the event is detached (optional, default document.documentElement)
• detail any an info to send with the event (optional, default null)

Returns Boolean true if emitted, false if done nothing

Special thanks

• Thanks Chris Ferdinandi for teaching about that way of adding event listeners: https://gomakethings.com/why-event-delegation-is-a-better-way-to-listen-for-events-in-vanilla-js/
• Thanks Sebastian De Deyne for this little inspiring utility: https://sebastiandedeyne.com/javascript-framework-diet/event-delegation/