Introducing LISN.js: handle user interactions and layout events + widgets! ⚡

Hey there awesome people! Firstly, let me briefly say hello, this will be my first post on dev.to 👋 I want to introduce you to my new project.

What is LISN.js?

In a nutshell, LISN.js is a flexible, full-featured and simple to use library for handling user gestures (drag, scroll, zoom, with any type of device) and interactions (like scrolling, clicking, etc) as well as observing elements for changes in viewport position, size and so on.

There are React wrappers available as a separate package. It works in
server-side rendering environments like Next.js.

LISN also comes with many awesome widgets, like collapsible, floating popup, modal, offcanvas menu, pager (carousel/slider/tabs), flex same-height, scrollbars (native scrolling), sortable, scroll-to-top button and page loader.

---

"Why not use X, Y and Z?" you say

So you go like, "Well there's Hammer.js for gesture handling, Waypoints for viewport observation, Trigger.js or GSAP for scroll based animations, Sortable.js for sortables, OverlayScrollbars for scrollbars, and gosh-you-name-it for modals, popups, sliders, and so on? What's new here 🤷

Well you can use all of those (and I'd probably recommend each one ❤️). But in general, do you prefer to install 15+ libraries, learn how to use each one, possibly survive a dependency hell, find out that some of them may not be actively maintained, some of them don't work in server-side rendering context, some of them are too rigid and don't allow for extensive customization, some of them don't work with touch or on browser X... (P.S. I'm not saying this is the case for any of the libraries I just mentioned)... or do you prefer to install 1 library that is:

• 100% vanilla TypeScript (no dependencies)
• Has React wrappers
• Extensively tested
• Highly optimized, no layout thrashing
• Works with server-side rendering
• Super flexible and customizable
• Simple to use

and in addition to the standard JavaScript API it has an HTML-only mode where you can do almost anything the full JS API can do without writing a single line of JavaScript.

Want a modal to open the first time the user scrolls to the middle of the page? Easy.

<div
  data-lisn-modal
  data-lisn-on-view="@open +target=top: 50% +rootMargin=-48%,0px +once"
>
  <p>
    Here's a modal popping up to tell you you've reached the middle of the page!
  </p>
  <p class="footnote">P.S. Don't do that, popups are annoying.</p>
</div>

Want scroll-tabs/sections that show the current section in the page and can scroll to it (smoothly and as slowly as you like)? And a cool configurable scrollbar (maybe as a progress bar)? Here, just sprinkle some CSS to taste.

  <div class="tabs">
    <div
      class="tab"
      data-lisn-ref="tab1"
      data-lisn-on-view="at @add-class:inview
                         +root=next.scrollable
                         +rootMargin=0px
                         +target=next-section1"
    >
      Intro
    </div>
    <div
      class="tab"
      data-lisn-ref="tab2"
      data-lisn-on-view="at @add-class:inview
                         +root=next.scrollable
                         +rootMargin=0px
                         +target=next-section2"
    >
      The real deal
    </div>
  </div>

  <div class="scrollable"
       data-lisn-scrollbar="positionV=top | click-scroll=false">
    <div
      data-lisn-ref="section1"
      data-lisn-on-click="@scroll-to: offsetY=-5, scrollable=this.scrollable
                          +target=prev-tab1 +oneWay"
    ></div><!-- target is the click target -->
    <div class="section">
      <h1>Yada yada...</h1>
      Does anyone even read intro?
      Norem hipsum color something something
    </div>

    <div
      data-lisn-ref="section2"
      data-lisn-on-click="@scroll-to: offsetY=-5, scrollable=this.scrollable
                          +target=prev-tab2 +oneWay"
    ></div>
    <div class="section">
      <h1>Now we're talking</h1>
      ...
    </div>
  </div>
</div>

🙄 But I'm an experienced dev and I write JavaScript TypeScript (React TypeScript!)

Sure, you can still do that with LISN and the syntax/API is just as simple and intuitive and even more powerful. (👉 Demos | Docs)

But for the curious, I'll explain how the HTML-only mode came about; well actually how and why LISN itself came to be!

The HTML-only mode was actually the original aspect of LISN before it underwent 3-4 stages of metamorphosis 🦋 You see, I was making a website... in Wordpress... (don't ask). And let me tell you, it ain't easy to make it look like and walk like and talk like the animal you want 🦖 A lot of the Wordpress plugins are limited, rigid and full of bugs.

Sigh... I just wanted to have nice, glitch-free customizable modals and collapsibles... And animate elements when they come into view... And scroll to an alert box when the page loads... And have a flexbox section with an image and text that stay the same height no matter what aspect ratio image I put in there (cause it's all dynamic™ you know). (If you've ever tried to do the last one and ended up writing 3 pages of polynomial equations and calculus you'll know my pain sense of reward.)

Well, I guess if you want a job done well, you gotta do it yourself. So I did. And then the idea came...

Ok, ok, docs, demos, now

I won't copy paste the quick start and doc here, but just refer you to the latest docs.

Official website | Demos | Docs | GitHub