Scrollmptious

Tiny vanilla-JS utility that fires different callbacks based on scroll direction.

Zero dependencies. ESM. About 80 lines of source. Useful for hide-on-scroll navbars or anything that needs to react when the user reverses direction.

Live demo →

Install

npm install scrollmptious

Or load it as an ES module directly in the browser:

<script type="module">
  import { scrollmptious } from 'https://esm.sh/scrollmptious';
  scrollmptious(document.querySelector('nav'));
</script>

Usage

The default behavior slides the target element off-screen on scroll-down and back on scroll-up — designed for fixed navbars:

import { scrollmptious } from 'scrollmptious';

scrollmptious(document.querySelector('nav'));

nav {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 60px;
  transition: top 0.25s ease-in-out;
}

Wire up your own callbacks instead of the default top-style toggle:

import { Scrollmptious } from 'scrollmptious';

const instance = new Scrollmptious(document.body, {
  onDown: ({ scrollTop }) => document.body.classList.add('hide-navs'),
  onUp:   ({ scrollTop }) => document.body.classList.remove('hide-navs'),
});

// Later:
instance.destroy();

Options

| Option | Default | Description | | -------------- | -------- | --------------------------------------------------------------------------- | | onUp | null | Called when scrolling up. Receives { direction, scrollTop, instance }. | | onDown | null | Called when scrolling down past the element's height. | | delta | 5 | Pixels of movement required before a direction change registers. | | scrollTarget | window | Element to listen on. Pass a scrollable container to scope detection. |

API

• new Scrollmptious(element, options) — returns an instance.
• scrollmptious(element, options) — convenience wrapper around the constructor.
• instance.destroy() — removes the scroll listener. Idempotent.

The plugin uses a passive scroll listener and requestAnimationFrame for throttling, so it stays cheap and never blocks the main thread.

Migrating from v1

v1 was a jQuery plugin. v2 is vanilla ESM. The renames:

| v1 (jQuery) | v2 (vanilla) | | ---------------------------------------- | -------------------------------------------------- | | $('nav').scrollmptious() | scrollmptious(document.querySelector('nav')) | | upFunction / downFunction | onUp / onDown | | this inside callbacks = jQuery element | callbacks receive { direction, scrollTop, instance } |

v1 had a latent bug where custom callbacks never ran (the option name and the property it checked diverged). v2 fixes that.

Development

npm install
npm test

Tests run against happy-dom via node --test.

License

MIT © Go Boldly Forward