Repository files navigation

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

• demo page /and itssource;

• home page of intence project alsousesviewport.js for its navigation menu.

In other words,viewport.js is similar tootherscrollspy [solutions](https://github.com/sxalexander/jquery-scrollspy), but has thefollowing advantages:

• it is written on vanilla javascript, does not have dependencies andworks anywhere;

• it has a simple and flexible API which shows:

• which section is currently displayed in the viewport;

• where is the viewport relatively to each section;

• where are the viewport edges relatively to each section;

• where should the viewport be scrolled to in order to show aparticular section.

Download and unpack thedistribution, or install it usingBower:

$ bower install vanilla-viewport

or npm:

$ npm install vanilla-viewport

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

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

Add thesection class to the sections:

<divid=firstSectionclass=section>    First section content goes here...</div><divid=secondSectionclass=section>    Second section content goes here...</div>

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

// use document.body if the whole page is scrollablevarmyViewport=document.getElementById('myViewport');varfirstSection=document.getElementById('firstSection');myViewport.addEventListener('scroll',function(){varlocation=firstSection.viewportTopLocation;console.log('The viewport is at '+location+' relatively to the first section');},false);

Section elements contain the following properties:

• viewportTopLoctaion - progress of a viewport scrolling through thesection. If the section is visible in the viewport, the value isbetween 0 (section start) and 1 (section end). Values <0 or >1 meanthat the section is outside of the viewport. This property reflectsthe location of the viewport as a whole;

• veiwportTopStart - precise position of the top edge of theviewport relatively to the section. The value has the same meaningas for theviewportTopLocation;

• viewportTopEnd - same for the bottom border of the viewport.

UseviewportTopLocation if you want to display a scrolling progressas a single value. UseviewportTopStart andviewportTopEndproperties together if you need to display the scrolling position as arange (like on a scrollbar), or if you need to know the rate of howmuch the viewport covers the section.

There are also the similar properties for the horizontal scrollingdirection:

• viewportLeftLocation - horizontal scrolling position of theviewport relatively to the section;

• viewportLeftStart - viewport left edge position;

• viewportLeftEnd - veiwport right edge position;

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

• viewportScrollTopTarget

• viewportScrollLeftTarget

You will need them to determine where to scroll the viewport when userclicks a menu button pointing to the section. Always usenaturalscroll when scrollingprogrammatically.

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

<divclass=viewportid=myViewport><divid=firstSectionclass=section>      First section content goes here...</div><divid=secondSectionclass=section>      Second section content goes here...</div></div>

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

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

If you change / create the sections dynamically after the pageload, invokeviewport.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 theirrespective viewports.

For the sake of performance, sections dimensions are cached upon pageload. It is assumed that section dimensions may only change uponwindow resize, so after it happens, the cached dimensions areupdated. But if in your application section dimensions may change forother reasons, invokeviewport.updateDimensions() after thathappens.

If you create a navigation panel reflecting the scrolling state,replace the scrollbars withintenceindicator: it designates a scrollable area in more clear and intuitiveway comparing to the ordinary scrollbar.

Follow me on twitter:https://twitter.com/asvd0