viewport-utility
v1.2.8
Published
JavaScript utility for the front end. Watches the viewport, stores/retrieves values and adds classes to the DOM.
Downloads
7
Readme
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-utilityDemo
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 [email protected] 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.