Taikonauten windowatch

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 TaikoLibWindowatch from '../index';

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

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

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

Work with breakpoints

Add breakpoint specification to your script’s entry point:

import TaikoLibWindowatch from '../index';

TaikoLibWindowatch.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
TaikoLibWindowatch.getBreakpoint();
// -> 's'

// get the current breakpoint specifications
TaikoLibWindowatch.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
TaikoLibWindowatch.isSmallerThan('m');
// if current breakpoint is s -> true

// check if the current breakpoint is larger than the given one
TaikoLibWindowatch.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 TaikoLibWindowatch from '../index';

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);
  }
}

TaikoLibWindowatch.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) => {};

TaikoLibWindowatch.addScrollListener(scrollHandler);
TaikoLibWindowatch.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'
TaikoLibWindowatch.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) => {};

TaikoLibWindowatch.addResizeListener(resizeHandler);
TaikoLibWindowatch.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) => {};

TaikoLibWindowatch.addBreakpointListener(breakpointChangeHandler);
TaikoLibWindowatch.removeBreakpointListener(breakpointChangeHandler);

Development & Playground

npm start

Made with ♡ at Taikonauten

GitHub

View Github