@unic/factory-breakpoint-manager

Lightweight breakpoint manager

Usage no npm install needed!

<script type="module">
  import unicFactoryBreakpointManager from 'https://cdn.skypack.dev/@unic/factory-breakpoint-manager';
</script>

README

factory-breakpoint-manager

Lightweight Breakpoint Manager who notifies you when the breakpoint switches or you can check for the current breakpoint.

Installation

$ npm install @unic/factory-breakpoint-manager

Importing

// ES6 Module
import createBreakpointManager from '@unic/factory-breakpoint-manager';

// CommomJS
const createBreakpointManager = require('@unic/factory-breakpoint-manager').default;

Usage/Quickstart

import createBreakpointManager from '@unic/factory-breakpoint-manager';

// Creating a new BreakpointManager (no pun intended)
const BreakpointManager = createBreakpointManager({
  breakpoints: {
    xs: 0,
    sm: 768,
    md: 992,
    lg: 1200,
  },
  unit: 'px'
});

// Subscribe to a breakpoint change
const subscriptionId = BreakpointManager.on('change', () => {

  // Read the current state of your BreakpointManager
  const currentState = BreakpointManager.getState();
  console.log(currentState);

  // Check if the breakpoint is currently value x
  if(BreakpointManager.matches('xs')) {
    console.log('Window width is currently between 0px and 767px');
  }

  // Check if the breakpoint is currently value x or y...
  if(BreakpointManager.matches(['xs', 'md', 'lg'])) {
    console.log('Window is currently on xs/md or lg');
  }

  // Check if matches is false can also result in what you need
  if(!BreakpointManager.matches('sm')) {
    console.log("Same result as when given ['xs', 'md', 'lg'] and checkig if it was true");
  }
});


// Unsubscribe at any given point
BreakpointManager.off(subscriptionId);

Best practises

Having to write your Breakpoints directly into your JS can be a real hazard to maintain, so I'd advise you to write your breakpoint configuration in a JSON file and load this json file into your JS and into your CSS preprocessor. With this you have a single source of truth for your breakpoints and it's very managable.

Good plugins to achieve this

API

BreakpointManager has own functionality and functionality provided by included composites.

Factory createBreakpointManager(options)

Own methods

Observer Composite
Documentation of these methods are extern

createBreakpointManager(options)

Create a new instance of a BreakpointManager

Returns: Object - BreakpointManager

Param Type Description
options Object Custom options

Example

const BreakpointManager = createBreakpointManager({
  breakpoints: {
    xs: 0,
    sm: 768,
    md: 992,
    lg: 1200,
  },
  unit: 'px'
});

// Or go with em as a unit

const BreakpointManager = createBreakpointManager({
  breakpoints: {
    xs: 0,
    sm: 48,
    md: 62,
    lg: 75,
  },
  unit: 'em'
});

getState()

Get the current state of your BreakpointManager.

Returns: Object - Returns current state of your BreakpointManager

Key Type Description
width Integer/Float Current Window width
breakpoint Object Current active breakpoint

Example

console.log(BreakpointManager.getState());

/*
Could return:
{
  width: 823,
  breakpoint: {
    name: 'sm',
    minWidth: 768
  }
}
*/

matches(test)

Check on which breakpoint you currently are.

Returns: Boolean - Ture if matching, false if not matching

Param Type Description
test String/Array Custom options

Example

if(BreakpointManager.matches('xs')) {
  console.log('Yes! current Breakpoint is xs');
}

if(BreakpointManager.matches(['xs', 'md', 'lg'])) {
  console.log('Current breakpoint is currently xs, md or lg');
}

if(!BreakpointManager.matches('sm')) {
  console.log('Current breakpoint is definitely not sm');
}

Information and Ressouces about factories

A factory function is simply a function that returns an object. Factory functions are often used in combination of composites to accomplish the factory/composition pattern.

Helpful Ressources:

Caveats

BreakpointManager is using window.innerWidth to read the width of the frame. This also means, if you have actual content that is 'wider' than 100% of your screen, the value of your BreakpointManager might not be correct, as it's not using document.documentElement.clientWidth which would read the correct value, but not incorporate the scrollbar in its calculation (which would result the BreakpointManager breakpoint of 768px to trigger at different widths than your CSS breakpoint at the same value). To avoid any problems, make sure you have overflow-x: hidden on your body, to avoid any overflow on the x-achsis, so window.innerWidth will always read the correct value.

License

Apache-2.0