# viewport-utility
[](LICENSE.md)
[](https://travis-ci.org/spatie/viewport-utility)
[](https://img.shields.io/codeclimate/github/spatie/viewport-utility.svg)
[](https://www.npmjs.com/package/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](LICENSE.md)), 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
``` bash
$ npm i viewport-utility
```
## Demo
There is a small [demo page](https://spatie.github.io/viewport-utility).
### Usage
``` js
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.
``` js
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.
``` js
// 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
``` js
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-'`.
``` css
.\$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
```
Default html needed when you don't override options:
```html
When using scroll functions: don't scroll under me
...
Scroll to top
Scroll to anchor
Scroll to anchor, only if out of view
...
Half page for iOS7
```
## Change log
Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
## Security
If you discover any security related issues, please email willem@spatie.be instead of using the issue tracker.
## Credits
- [Willem Van Bockstal](https://github.com/willemvb)
- [All Contributors](../../contributors)
## About Spatie
Spatie is webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects [on our website](https://spatie.be/opensource).
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.