Sign inDemoInstall


Package Overview
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies



A performant and lightweight ES6 module for detecting scroll activity (direction + location) for X and/or Y axis

Version published
Weekly downloads
decreased by-8.11%
Install size
2.35 MB
Weekly downloads



Detect Scroll 📜️ 🔍️ 👀️

A performant and lightweight (~1.6kb) ES6 module for detecting scroll activity (direction + location) for X and/or Y axis

Coverage:statements Coverage:functions Coverage:lines License: MIT


The default scroll event listener is amazing and all, but isn't exactly the most usable tool out of the box. It's all, "Hey look, a user scrolled!". And I'm like "Great! But like, in what direction and where did they stop?". And then it's all like, "IDFK, how about you do some math and figure it out".

In short, this little library adds a handful of helpful CustomEvent's which make scroll detection a little more insightful.

View Example

Note: Open your console to preview debug mode


npm install @egstad/detect-scroll


Example One

  1. Install and import detectScroll.
  2. Select an individual element you'd like to monitor the scroll activity of. Can be a string selector (ie: '.scroll-container'), or any valid HTMLElement. In our case, we'll use the window.
  3. Register the Event listeners that you'd like to use. Any events that are not explicitly defined will not fire.
  4. If/when you want to destroy the instance, running destroy() will remove all event listeners.
import detectScroll from '@egstad/detect-scroll'

// setup instance & events
const instance = new detectScroll(window, {
  events: {
    scrollUp: foo(),
    scrollDown: bar(),

// if/when you want to destroy the instance and events

Example Two

Another way to get up and running with this library is to handle the events yourself. This option registers and dispatches all Events, but you'll have to add/remove the event listeners yourself.

import detectScroll from '@egstad/detect-scroll'

// setup instance
const instance = new detectScroll(window)

// setup events
window.addEventListener('scrollUp', foo)
window.addEventListener('scrollDown', bar)

// if/when you want to destroy all events
window.removeEventListener('scrollUp', foo)
window.removeEventListener('scrollDown', bar)

Default Configuration

const instance = new detectScroll(window, {
  vertical: true,
  horizontal: true,
  passiveMode: true,
  debugMode: false,
  events: undefined,

Properties & Events worth knowing about

Optional Properties

Optional PropertiesDefault ValueDescription
verticaltrueRegisters & Dispatches y-axis activity
horizontaltrueRegisters & Dispatches x-axis activity
passiveModetrueDetermines if scroll event is passive or not
debugModefalseLogs events in console as they dispatch
eventsundefinedEvent overrides (see Events section for more)


Scroll events are dispatched using CustomEvent's. Here's a gorgeous list of all 10.

If you would like to a specific selection of them, check out this example.

Custom Event NameDescription
scrollStartFired when scrolling begins
scrollStopFired when scrolling ends
scrollXFired every time x position updates
scrollYFired every time y position updates
scrollUpFired when scrolling up
scrollDownFired when scrolling down
scrollLeftFired when scrolling left
scrollRightFired when scrolling right
scrollMinXFired when the left-most part of el/window is reached
scrollMaxXFired when the right-most part of el/window is reached
scrollMinYFired when top of element/window is reached
scrollMaxYFired when bottom of element/window is reached
Event Template
const foo = (ev) => {

const instance = new detectScroll(window, {
  events: {
    // exclude any of these and the event's won't be registered or fired
    scrollStart: foo,
    scrollStop: foo,
    scrollX: foo,
    scrollY: foo,
    scrollUp: foo,
    scrollDown: foo,
    scrollLeft: foo,
    scrollRight: foo,
    scrollMinX: foo,
    scrollMaxX: foo,
    scrollMinY: foo,
    scrollMaxY: foo,



Last updated on 03 Nov 2023

Did you know?


Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap


Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc