Get new jQuery plugins just once a week



June 5, 2015

Viewport-js | Javascript library to report viewport position relatively to the sections

Viewport-js is a small js library for showing viewport position relatively to the reading sections.

Created by asvd



viewport-js js lib



viewport.js is a small javascript library (2152 bytes minified) which ships the document sections with additional properties containing the viewport scrolling position relatively to the sections. Using these properties you can create a custom scrolling indicator or a navigation menu precisely reflecting the scrolling state:

In other words, viewport.js is similar to other scrollspy [solutions] (, but has the following advantages:


Download and unpack the distribution, or install it using Bower:

$ bower install vanilla-viewport

or npm:

$ npm install vanilla-viewport

Load the viewport.js in a preferable way (that is an UMD module):

<script src="viewport.js"></script>

Add the section class to the sections:

<div id=firstSection class=section>
    First section content goes here...

<div id=secondSection class=section>
    Second section content goes here...

This is it - now the sections are shipped with additional properties and you can fetch them on viewport scroll in order to reflect the scrolling state in an indicator:

// use document.body if the whole page is scrollable
var myViewport = document.getElementById('myViewport');
var firstSection = document.getElementById('firstSection');

    function() {
        var location = firstSection.viewportTopLocation;
            'The viewport is at ' + location +
            ' relatively to the first section'

Section elements contain the following properties:

Use viewportTopLocation if you want to display a scrolling progress as a single value. Use viewportTopStart and viewportTopEnd properties together if you need to display the scrolling position as a range (like on a scrollbar), or if you need to know the rate of how much the viewport covers the section.

There are also the similar properties for the horizontal scrolling direction:

The following properties contain the scroll targets where the viewport should be scrolled in order to display a particular section:

You will need them to determine where to scroll the viewport when user clicks a menu button pointing to the section. Always use natural scroll when scrolling programmatically.

If a viewport is not the whole page, add the viewport class to the the element which actually performs scrolling:

<div class=viewport id=myViewport>
  <div id=firstSection class=section>
      First section content goes here...

  <div id=secondSection class=section>
      Second section content goes here...

The viewport element additionally contains the currentSection property which points to the section element currently visible in the viewport (more precisely, the section which is the closest to the viewport):

var currentSection = document.getElementById('myViewport').currentSection;

If you change / create the sections dynamically after the page load, invoke viewport.reset() to update the listeners.

You may also have several scrollable viewports with nested sections, in this case the sections will contain the data related to their respective viewports.

For the sake of performance, sections dimensions are cached upon page load. It is assumed that section dimensions may only change upon window resize, so after it happens, the cached dimensions are updated. But if in your application section dimensions may change for other reasons, invoke viewport.updateDimensions() after that happens.

If you create a navigation panel reflecting the scrolling state, replace the scrollbars with intence indicator: it designates a scrollable area in more clear and intuitive way comparing to the ordinary scrollbar.


Follow me on twitter:


Related posts:


To install using Bower
bower install viewport

viewport-js js lib

jQuery plugin

Sign up for our weekly newsletter.

* We won't spam you ever