Skrollr - Parallax scrolling for the masses

Skrollr is a stand-alone parallax scrolling javascript library for mobile (Android + iOS) and desktop in about 12k minified with designer friendly, no JavaScript skills needed and just plain CSS and HTML.

Source: github.com

1. INCLUDE JS FILES

<script type="text/javascript" src="dist/skrollr.min.js"></script>

2. HTML

<div id="bg1" data-0="background-position:0px 0px;" data-end="background-position:-500px -10000px;"></div>
<div id="bg2" data-0="background-position:0px 0px;" data-end="background-position:-500px -8000px;"></div>
<div id="bg3" data-0="background-position:0px 0px;" data-end="background-position:-500px -6000px;"></div>

<div id="progress" data-0="width:0%;background:hsl(200, 100%, 50%);" data-end="width:100%;background:hsl(920, 100%, 50%);"></div>

<div id="intro" data-0="opacity:1;top:3%;transform:rotate(0deg);transform-origin:0 0;" data-500="opacity:0;top:-10%;transform:rotate(-90deg);">
	<h1><a href="https://github.com/Prinzhorn/skrollr">skrollr</a></h1>
	<h2>parallax scrolling for the masses</h2>
	<p>let's get scrollin' ;-)</p>
	<p class="arrows">▼&nbsp;▼&nbsp;▼</p>
</div>

<div id="transform" data-500="transform:scale(0) rotate(0deg);" data-1000="transform:scale(1) rotate(1440deg);opacity:1;" data-1600="" data-1700="transform:scale(5) rotate(3240deg);opacity:0;">
	<h2>transform</h2>
	<p>scale, skew and rotate the sh** out of any element</p>
</div>

<div id="properties" data-1700="top:100%;" data-2200="top:0%;" data-3000="display:block;" data-3700="top:-100%;display:none;">
	<h2>all numeric properties</h2>
	<p>width, height, padding, font-size, z-index, blah blah blah</p>
</div>

3. JAVASCRIPT

var s = skrollr.init({
	edgeStrategy: 'set',
	easing: {
		WTF: Math.random,
		inverted: function(p) {
			return 1-p;
		}
	}
});

4. OPTIONS

On the JavaScript part there's not much to do (you can, if you want to!). So if you only know CSS and HTML, perfect.

skrollr.init([options])

All there is to do is to call skrollr.init([options]); which returns an instance of the singleton skrollr class. Subsequent calls to init() will just return the same skrollr instance again.

Possible options for init() are

smoothScrolling=true

Smooth scrolling smoothens your animations. When you scroll down 50 pixels, the animations will transition instead of jumping to the new position.

The global setting can be overridden per element by setting data-smooth-scrolling to on or off.

smoothScrollingDuration=200

The number of milliseconds the animations run after the scroll position changed the last time.

constants={}

An object containing integers as values. The keys can contain [a-z0-9_]. They do not need a leading underscore.

Example: data-_myconst-200 and skrollr.init({constants: {myconst: 300}}) result in data-500.

scale=1

By default, skrollr uses the largest key frame and makes document height + viewport height this high, thus the max possible scroll top offset. If your animation runs too fast or too slow, just adjust the scale value.

scale only affects keyframes in absolute mode.

When forceHeight is set to false, scale is ignored.

scale affects constants as well.

scale does only affect key frames in absolute mode, e.g. data-500 but not data-top.

forceHeight=true

true: Make sure the document is high enough that all key frames fit inside. Example: You use data-1000, but the content only makes the document 500px high. skrollr will ensure that you can scroll down the whole 1000px. Or if you use relative mode, e.g. data-top-bottom, skrollr will make sure the bottom of the element can actually reach the top of the viewport.

false: Don't manipulate the document and just keep the natural scrollbar.

mobileCheck=function() {...}

This option allows you to pass a function to skrollr overwriting the check for mobile devices. The function should return true when mobile scrolling should be used and false if not.

The default looks like this

function() {
    return (/Android|iPhone|iPad|iPod|BlackBerry/i).test(navigator.userAgent || navigator.vendor || window.opera);
}

mobileDeceleration=0.004

The amount of deceleration for momentum scrolling on mobile devices. This options tells skrollr how fast or slow you want the scrolling to stop after the user lifted his finger.

Set it to 1 to disable momentum scrolling.

edgeStrategy='set'

This option specifies how to handle animations when the scroll position is outside the range on the keyframes (i.e. before the first or after the last keyframe).

One of three options are possible

• set (default): When before/after the first/last keyframe, apply the styles of the first/last keyframe to the element.
• ease: Same as set, but the values will be transformed using the given easing function.
• reset: When before/after the first/last keyframe, apply the styles which the element had before skrollr did anything. This means resetting the class attribute as well as removing all styles which have been applied to the style property. This means the element won't have any skrollable-*CSS classes.

Example:

Given the following element with two keyframes

<div data-1000="left:0%;top:0%;" data-2000="left:50%;top:100%;" style="left:-100%;" class="section"></div>

and the following easing function which always returns 0.5 (I know it's pointless, but it's just an example. A real world example would be an easing function that represents a curve and starts somewhere between 0 and 1, but not at 1)

function(p) {
    return 0.5;
}

and imagine the scrollbar is at 237, which is below the first keyframe which is at 1000.

• set will result in <div style="left:0%;top:0%;" class="section skrollable skrollable-before"></div>which is plain data-1000.
• ease will result in <div style="left:25%;top:50%;" class="section skrollable skrollable-before"></div>which is 0.5 * data-1000.
• reset will result in <div style="left:-100%;" class="section"></div> which is what the element originally had. Note how top is missing.

beforerender

A listener function that gets called each time right before we render everything. The function will be passed as an object with the following properties:

{
    curTop: 10, //the current scroll top offset
    lastTop: 0, //the top value of last time
    maxTop: 100, //the max value you can scroll to. curTop/maxTop will give you the current progress.
    direction: 'down' //either up or down
}

Returning false will prevent rendering.

render

A listener function that gets called right after we finished rendering everything. The function will be passed with the same parameters as beforerender.

Example

skrollr.init({
    render: function(data) {
        //Log the current scroll position.
        console.log(data.curTop);
    }
});

keyframe

Experimental

In order to receive keyframe events from an element, add the data-emit-events attribute to the element. The keyframe function will be called with three arguments

1. The element that passed the keyframe.
2. The name of the keyframe, camel-cased (see example).
3. The direction the user is scrolling.

Example:

<div
    data-500="..."
    data-top-bottom="..."
    data-_offset-center="..."
    data-emit-events
>
    Some content
</div>

skrollr.init({
    keyframe: function(element, name, direction) {
        //name will be one of data500, dataTopBottom, data_offsetCenter
    }
});

Note: this is experimental, expect the API to change! Originally I wanted to emit the events right on the element, so you could do this

//Wouldn't this be nice?
document.querySelector('#foo').addEventListener('skrollr.dataTopBottom.up', function() {
    //#foo just passed the data-top-bottom keyframe while scrolling up
}, false)

but IE.

easing

An object defining new easing functions or overwriting existing ones. Easing functions get just one argument, which is a value between 0 and 1 (the percentage of how much of the animation is done). The function should return a value between 0 and 1 as well, but for some easings a value less than 0 or greater than 1 is just fine.

An easing function basically transforms the timeline for an animation. When the animation should be 50% done, you can transform it to be 90% done or whatever your function does.

Example:

skrollr.init({
    easing: {
        //This easing will sure drive you crazy
        wtf: Math.random,
        inverted: function(p) {
            return 1 - p;
        }
    }
});

You can now use the easing functions like any other.

skrollr ships with some built in functions:

• linear: The default. Doesn't need to be specified.
• quadratic: To the power of two. So 50% looks like 25%.
• cubic: To the power of three. So 50% looks like 12.5%
• begin/end: They always return 0 or 1 respectively. No animation.
• swing: Slow at the beginning and accelerates at the end. So 25% -> 14.6%, 50% -> 50%, 75% -> 85.3%
• sqrt: Square root. Starts fast, slows down at the end.
• outCubic
• bounce: Bounces like a ball.

5. PUBLIC API

Calling init() returns an instance of skrollr which exposes a public api.

refresh([elements])

Reparses all given elements. You can pass a single element or an array-like element (Array, NodeList or jQuery object)

Useful when

• Elements in relative mode change and need to be updated.
• Data-attributes are manipulated dynamically.
• New elements are added to the DOM and should be controlled by skrollr.

When no elements are given, all elements in the document will be parsed again. In fact, when callingskrollr.init() skrollr uses refresh() without parameters internally.

Time consuming operations, should not be called on every rendering.

relativeToAbsolute(element, viewportAnchor, elementAnchor)

Returns an integer which represents the absolute scroll position which correlates to the relative anchor.

element must be a DOM element.

viewportAnchor and elementAnchor must be one of top, center or bottom

Example:

var offset = s.relativeToAbsolute(document.getElementById('foo'), 'top', 'bottom');

//offset contains the scroll position at which #foo's bottom is at the top of the viewport.
//If you now use setScrollTop(offset) or animateTo(offset) #foo's bottom will be perfectly aligned with the top of the viewport. Yay.

getScrollTop()

Returns the current scroll offset in pixels. Normalizes different browser quirks and handles mobile scrolling.

getMaxScrollTop()

Returns the number of pixels that can be scrolled down in total. If forceHeight is true, that's usually the largest keyframe. Otherwise it's the height of the document minus the viewport height.

setScrollTop(top[, force = false])

Sets the top offset using window.scrollTo(0, top) on desktop or updating the internal state in case of mobile scrolling.

When force is set to true, skrollr will jump to the new position without any kind of transition. By default, the global smoothScrolling setting applies.

isMobile()

Returns if skrollr runs in mobile mode (see also mobileCheck option).

animateTo(top[, options])

Animates the scroll position from current position to top. Possible options are

duration

How long the animation should run in milliseconds. The default is 1000 or one second.

easing

The name of an easing function. The same functions can be used as for property animations. Default islinear .

done

A function to be called after the animation finished. When you pass a top value, which is the same as the current, then the function will be called immediately. The function gets a boolean argumentinterrupted which indicates if the animation was interrupted by stopAnimateTo or finished to the end.

stopAnimateTo()

Stops the animation and calls the done callback passing true as interrupted arguments.

isAnimatingTo()

Returns if an animation caused by animateTo is running.

on(name, fn)

Set a listener function for one of the events described in the options section (beforerender, render, keyframe). Only one listener can be attached at a given time. This method overwrites the current listener, if any.

off(name)

Removes the listener for the given event.

destroy()

Destroys skrollr. All class and style attributes will be set to the values they had before.

• The "main" example
• "Classic" parallax with different sections and parallax images between the gaps
• Demonstrating different anchors
• Demonstrating data-anchor-target
• Pausing the scrolling for a moment to do other animations
• Drawing a SVG path
• Using two custom easing functions to create a circular motion
• Parallax background with constant speed
• gradientsmotherfucker