Relativity

Relativity is a library that uses screen scroll events and position to animate elements within the viewport. It can be used to create a parallax effect, scaling, rotations, fade in and out, and so much more.

Installation

npm install --save relativity

bower install relativity

Usage

Relativity uses jQuery for DOM manipulation so you'll need that to be available before Relativity.

<script src="https://code.jquery.com/jquery-1.12.1.min.js"></script>
<script src="relativity.js"></script>

Relativity makes itself available as a global variable which you can use to create a new instance like this:

var relativity = new Relativity(options);

Options

There are a number of options that you can use when initializing Relativity. You can either pass a JSON array into options.containers which describes the containers and the elements inside them or you can defined the containers and movements in your HTML and let Relativity find them.

Option	Type	Values	Description
positionPropery	String	transform / position	Specificies whether to use CSS3 transforms or top/left positioning to move objects
supports3D	Boolean	true / false	Specificies whether to use CSS3 transform3d or transform
containers	Array	[]	Specifies which elements to use as containers and the elements within them

Movements

Relativity includes a number of built in movements that you can use to animate elements inside of containers.

Left | Right | Up | Down

Reveal

Scale

Events

Relativity also fires off events if you need more control over the animations or want to use Relativity as a waypoints solution.

On Screen

When a container is on screen it will trigger an event after every window.scroll event. You can listen to it like this:

$('.myContainer').on('relativity:onscreen', function(event, container, percentage) {
    console.log(container);
    // { top: '', bottom: '', height: '', $element: '', elements: [], elementsCount: 0 }
});

Off Screen

When a container switches from being on screen to off screen it will trigger a single event and include a direction parameter that can be up or down.

$('.myContainer').on('relativity:offscreen', function(event, container, direction) {
    console.log(container);
    // { top: '', bottom: '', height: '', $element: '', elements: [], elementsCount: 0 }

    console.log(direction);
    // 'up' | 'down'
});

Update Elements

Relativity needs to know a few things about the page height and screen size in order to accurately calculate which elements are on screen. It already includes a listener to detect screen resize events however these don't detect changes to the height of the page if something is added to the DOM. If you add anything to the DOM or adjust the height of an element dynamically you will need to ask Relativity to recalculate everything. It's super simple though, just trigger an event on the document like this:

$(document).trigger('relativity:update');