fabiomcosta / breakdancer

A breakpoint tracking utility

breakdancer

Breakdancer is a small utility library that helps developing and using ergonomic breakpoints. Devices and sizes will always change, human ergonomics like palm, wrist, lap, desk, wall never will.

Table of Contents

• Installation
• API
  • .width()
  • .height()
  • .viewport()
  • .changed()
  • .currently()
  • .breakpoint
• License

Installation

The module is released in the public npm registry and can be installed by running the following command in your terminal:

npm install --save breakdancer

Please do note that:

• This module was written from a browser environment so it depends on window and document to be available in the global scope. We do fallback to a polyfill if those are missing so the module should not break in a Node.js environment.
• The module is written in ES6, so make sure that you environment supports this or use a transpiler like Babel to compile the code.

API

The Breakdancer constructor is exported as default interface of this module and can be imported using:

import Breakdancer from 'breakdancer';

The Breakdancer constructor accepts 2 arguments which are your specification ergonomic or just breakpoints and an optional reference to a custom window object which should be used for view port information. The specification can either be an object where the key of the object is name and the value the width/height specification or an array of object where the objects have a name property.

var breakpoints = new Breakdancer([
  { 
    name: 'wrist',
    width: 320
  },
  {
    name: 'palm',
    width: 800,
    heigt: 600
  }
]);

The width and/or height that you specified should be seen as a minimum value. So when you specify 320 as width for wrist that means that 0 - 319 will trigger as wrist breakpoint. If width and height are both set it needs to satisfy the minim value of height as well before our checks move to the next breakpoint.

Now that everything is specified we can look at which methods are exposed on the created instance. In all examples we assume that the code above is used as example.

width()

Returns the width of the current view port.

breakpoints.width()  // 390

height()

Returns the height of the current view port.

breakpoints.height(); // 509

viewport()

Returns both the height and width of the current view port as an object.

breakpoints.viewport() // { width: 390, height: 509 }

changed()

Check if the view port and therefor our specified breakpoints have changed since the last time we've called the changed method. When constructing an instance we automatically check what our current satisfied breakpoint is. This method returns a boolean as indication if a change has occurred.

breakpoints.changed() // false

.. resize the browser ..

breakpoints.changed() // true

The method accepts an optional viewport argument if you want to test a different viewport configuration. If none is provided it will use the viewport information from the .viewport() method.

currently()

Calculates what we're currently triggering as view port. It does by iterating over the specified breakpoints and see if they are satisfying in the current view port. The name of the triggered breakpoint is returned as string.

breakpoints.currently(); // desktop

The method accepts an optional viewport argument if you want to test a different viewport configuration. If none is provided it will use the viewport information from the .viewport() method.

.breakpoint

A cached value that is used to see if the breakpoint is changed. This is updated when the .changed() method is called. So it's advised to use .changed() and .breakpoint over manually calling the .currently() method for figuring out the current break point.

console.log(breakpoints.breakpoint) // wrist

breakpoints.changed();
console.log(breakpoints.breakpoint) // palm

License

MIT