JavaScript utility for the front end. Watches the viewport, stores/retrieves values and adds classes to the DOM.

Usage no npm install needed!

<script type="module">
  import viewportUtility from '';



Software License Build Status Code Climate npm

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.


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.


$ npm i viewport-utility


There is a small demo page.


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


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'


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


disableScroll() // on the root element
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


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



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

<html data-viewport 

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.


Please see CONTRIBUTING for details.


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


About Spatie

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


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