Code Monkey home page Code Monkey logo

viewport's Introduction

viewport.js

viewport.js is a small javascript library (1566 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] (https://github.com/sxalexander/jquery-scrollspy), but has the following advantages:

  • it is written on vanilla javascript, does not have dependencies and works 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 a particular section.

Usage

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

$ bower 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>

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

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');

myViewport.addEventListener(
    'scroll',
    function() {
        var location = 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 the section. If the section is visible in the viewport, the value is between 0 (section start) and 1 (section end). Values <0 or >1 mean that the section is outside of the viewport. This property reflects the location of the viewport as a whole;

  • veiwportTopStart - precise position of the top edge of the viewport relatively to the section. The value has the same meaning as for the viewportTopLocation;

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

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:

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

  • viewportLeftStart - viewport left edge position;

  • viewportLeftEnd - veiwport right edge position;

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

  • viewportScrollTopTarget

  • viewportScrollLeftTarget

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>

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

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: https://twitter.com/asvd0

viewport's People

Contributors

asvd avatar kolumb avatar

Watchers

James Cloos avatar tx avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.