viewport-utility

Viewport-utility watches the browser and updates DOM classes and JS properties for easy access in your script or stylesheet. It also provides some simple functions to control scroll behaviour and a fallback for vh units in older browsers.

Postcardware

You're free to use this package (it's MIT-licensed), but if it makes it to your production environment you are required to send us a postcard from your hometown, mentioning which of our package(s) you are using.

Our address is: Spatie, Samberstraat 69D, 2060 Antwerp, Belgium.

The best postcards will get published on the open source page on our website.

Installation

$ npm i viewport-utility

Demo

There is a small demo page.

Usage

 
var viewport = require("viewport-utility").init({})

Options

You can change these before init(), or pass an object in init(options).

All config values can be overwritten by data-attributes on the root element.

 
    root: $('[data-viewport]'), // Typically on the HTML element
    toolbar: $('[data-viewport-toolbar]'), // When scrolling to an offset, take element into account
    vhItems: $('[data-viewport-vh]'), // Fix vh units for older browsers & iOS7
    scrollLinks: $('[data-viewport-scroll]'), // Scroll to anchor in href
    classPrefix: '$viewport-',
    lang: 'en', // Set by lang-attribute on root element
    // Default config
    config: {
        scrollOffset: 0,  // Add some space when scrolling to an offset
        small: 768, // Breakpoint
        start: 0, // Top margin before viewport is 'started'
        end: 0, // Bottom margin before viewport is 'ended'
    },

Properties

Following properties are updated, and can be usefull in your app code.

 
// Properties
height: 0,
width: 0,
start: 0, // Beginning of viewport relative to document
end: 0, // End of viewport relative to document
state: {
    scrollDisabled : false,
    small: false,
    large: false,
    scrolling: false,
    started: false,
    ended: false,
    loaded: false,
},
orientation: {
    portrait: false,
    landscape: false
},
direction: {
    down: false,
    up: false
}

Functions

 
disableScroll() // on the root element
enableScroll() 
init(options) // init module with options
isTopInView(target) // yes or no for offset or $element
scrollTo(target, whenInView) // scroll to offset, selector or $element, also to elements that are visible already (default:true)
scrollToHash() // scroll to hash in url, typically on page load
update() // update handlers and module

CSS

Classes you can use in Sass. Default setting is classPrefix: '$viewport-'.

 
.\$viewport-loading{}
.\$viewport-loaded{}
.\$viewport-orientation-portrait{}
.\$viewport-orientation-landscape{}
.\$viewport-direction-down{}
.\$viewport-direction-up{}
.\$viewport-small{}
.\$viewport-large{}
.\$viewport-started{}
.\$viewport-ended{}
.\$viewport-scrolling{}
.\$viewport-scroll-disabled{}

DOM

Data-attributes on root element will override the js options. The $viewport-loading class will be removed on page load.

<html data-viewport 
      data-viewport-small="900"
      data-viewport-start="100"
      data-viewport-end="100"
      data-viewport-scrolloffset="50"
      class="$viewport-loading">

Default html needed when you don't override options:

<div data-viewport-toolbar>When using scroll functions: don't scroll under me</div>
...
<a data-viewport-scroll href="#">Scroll to top</a>
<a data-viewport-scroll=true href="#anchor">Scroll to anchor</a>
<a data-viewport-scroll=false href="#anchor">Scroll to anchor, only if out of view</a>
...
<div data-viewport-vh="50">Half page for iOS7</div>

Change log

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email willem@spatie.be instead of using the issue tracker.

Credits

About Spatie

Spatie is webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.

License

The MIT License (MIT). Please see License File for more information.