Windowatch is a singleton class managing scroll-, resize- and breakpoint-change events globally. It uses passive resize & scroll event listeners and requestAnimationFrame to optimize dom interactions (get, update). It removes unnecessary window event listeners automatically, if no listeners are attached.

Installation

npm install --save @taikonauten/windowatch

Usage

Retrieve env properties

import Windowatch from '@taikonauten/windowatch';

// get the current window width
let width = Windowatch.getWindowWidth();
// -> 2560

// get the current window height
let height = Windowatch.getWindowHeight();
// -> 1440

// get the current vertical window scroll position
let scrollY = Windowatch.getScrollY();
// -> 42

Work with breakpoints

Add breakpoint specification to your script's entry point:

import Windowatch from '@taikonauten/windowatch';

Windowatch.setBreakpointSpecs({
  s: { min: null, max: 899 },
  m: { min: 900, max: 1199 },
  l: { min: 1200, max: null }
});

ℹ️ You can enhance the specifications of each breakpoint with your own information.

You can then receive information about the current breakpoint and its specs.

// get the current breakpoint name
Windowatch.getBreakpoint();
// -> 's'

// get the current breakpoint specifications
Windowatch.getBreakpointSpec();
// -> { min: null, max: 899 }

Or you can check if the current breakpoint is smaller or larger than another one. Both methods are called with a breakpoint name.

// check if the current breakpoint is smaller than the given one
Windowatch.isSmallerThan('m');
// if current breakpoint is s -> true

// check if the current breakpoint is larger than the given one
Windowatch.isBiggerThan('m');
// if current breakpoint is s -> false

Working with events

You can add 3 types of event listeners:

• scroll listener
• resize listener
• breakpoint listener

Each callback can return another function which is called at the end of a frame. Do all measurements and calculations first and put modifications like adding or removing classes in the listener callback.

Scroll listener example:

import Windowatch from '@taikonauten/windowatch';

const scrollHandler = (scrollY) => {
  // dom measurements
  let measurement = $element.classList.contains('block--foo');

  // return update callback (optional)
  // gets called at the end of the frame
  return () => {
    // dom updates
    $element.classList.toggle('block--bar', measurement);
  }
}

Windowatch.addScrollListener(scrollHandler);

Scroll event

You can add and remove scroll listeners which are called after the scroll position of the document has changed. The callback function accepts a single parameter, representing the current vertical scroll position.

const scrollHandler = (scrollY) => {};

Windowatch.addScrollListener(scrollHandler);
Windowatch.removeScrollListener(scrollHandler);

You can call addScrollListener with a second parameter, if your callback should only be called at specific breakpoints.

ℹ️ You need to specify breakpoints first to use this feature.

// The scrollHandler function is only called,
// if the current breakpoint has the name 'm' or 'l'
Windowatch.addScrollListener(scrollHandler, ['m', 'l']);

Resize event

You can add a callback function which is triggered after the size of the document has changed. This callback receives the width and the height of the window as its parameter.

const resizeHandler = (width, height) => {};

Windowatch.addResizeListener(resizeHandler);
Windowatch.removeResizeListener(resizeHandler);

Breakpoint event

If you do not need to react to each and every resize event but only if the current breakpoint has changed, you can register a breakpoint listener. The callback function is called with the new breakpoint and its related specifications as its parameters.

ℹ️ You need to specify breakpoints first to use this feature.

const breakpointChangeHandler = (breakpoint, spec) => {};

Windowatch.addBreakpointListener(breakpointChangeHandler);
Windowatch.removeBreakpointListener(breakpointChangeHandler);

Development & Playground

npm start

Tests

Running the tests requires Chrome or Brave to be installed on in local environment.

To execute all tests, run the following command:

npm run test

In case you are getting an error regarding the missing CHROME_BIN environment variable, please follow this guide:

• locate Chrome or Brave binary by running ls /usr/bin | grep 'chrome\|brave'
• update the CHROME_BIN env variable by running export CHROME_BIN=/usr/bin/brave-browser

Migration

Changes in 2.x

Update the main import

-import {windowatch as TaikoLibWindowatch} from '@libs/taiko-lib-windowatch';
+import TaikoLibWindowatch from '@taikonauten/windowatch';

Changes in 2.1

Update the main import

-import TaikoLibWindowatch from '@taikonauten/windowatch';
+import Windowatch from '@taikonauten/windowatch';

Made with ♡ at Taikonauten