Stellar.js - Parallax scrolling made easy

Related tags

Scroll stellar.js
Overview

Build Status Gitter

Stellar.js

PLEASE NOTE: This project is no longer maintained. If parallax scrolling is something you care about, please apply to become a contributor to this project.

Parallax scrolling made easy

Full guide and demonstrations available at the official Stellar.js project page.

Download

Get the development or production version, or use a package manager.

Getting Started

Stellar.js is a jQuery plugin that provides parallax scrolling effects to any scrolling element. The first step is to run .stellar() against the element:

// For example:
$(window).stellar();
// or:
$('#main').stellar();

If you're running Stellar.js on 'window', you can use the shorthand:

$.stellar();

This will look for any parallax backgrounds or elements within the specified element and reposition them when the element scrolls.

Mobile Support

Support in Mobile WebKit browsers requires a touch scrolling library, and a slightly tweaked configuration. For a full walkthrough on how to implement this correctly, read my blog post "Mobile Parallax with Stellar.js".

Please note that parallax backgrounds are not recommended in Mobile WebKit due to performance constraints. Instead, use parallax elements with static backgrounds.

Parallax Elements

If you want elements to scroll at a different speed, add the following attribute to any element with a CSS position of absolute, relative or fixed:

<div data-stellar-ratio="2">

The ratio is relative to the natural scroll speed, so a ratio of 0.5 would cause the element to scroll at half-speed, a ratio of 1 would have no effect, and a ratio of 2 would cause the element to scroll at twice the speed. If a ratio lower than 1 is causing the element to appear jittery, try setting its CSS position to fixed.

In order for Stellar.js to perform its calculations correctly, all parallax elements must have their dimensions specified in pixels for the axis/axes being used for parallax effects. For example, all parallax elements for a vertical site must have a pixel height specified. If your design prohibits the use of pixels, try using the 'responsive' option.

Parallax Backgrounds

If you want an element's background image to reposition on scroll, simply add the following attribute:

<div data-stellar-background-ratio="0.5">

As with parallax elements, the ratio is relative to the natural scroll speed. For ratios lower than 1, to avoid jittery scroll performance, set the element's CSS 'background-attachment' to fixed.

Configuring Offsets

Stellar.js' most powerful feature is the way it aligns elements.

All elements will return to their original positioning when their offset parent meets the edge of the screen—plus or minus your own optional offset. This allows you to create intricate parallax patterns very easily.

Confused? See how offsets are used on the Stellar.js home page.

To modify the offsets for all elements at once, pass in the options:

$.stellar({
  horizontalOffset: 40,
  verticalOffset: 150
});

You can also modify the offsets on a per-element basis using the following data attributes:

<div data-stellar-ratio="2"
     data-stellar-horizontal-offset="40"
     data-stellar-vertical-offset="150">

Configuring Offset Parents

By default, offsets are relative to the element's offset parent. This mirrors the way an absolutely positioned element behaves when nested inside an element with a relative position.

As with regular CSS, the closest parent element with a position of relative or absolute is the offset parent.

To override this and force the offset parent to be another element higher up the DOM, use the following data attribute:

<div data-stellar-offset-parent="true">

The offset parent can also have its own offsets:

<div data-stellar-offset-parent="true"
     data-stellar-horizontal-offset="40"
     data-stellar-vertical-offset="150">

Similar to CSS, the rules take precedence from element, to offset parent, to JavaScript options.

Confused? See how offset parents are used on the Stellar.js home page.

Still confused? See what it looks like with its default offset parents. Notice how the alignment happens on a per-letter basis? That's because each letter's containing div is its default offset parent.

By specifying the h2 element as the offset parent, we can ensure that the alignment of all the stars in a heading is based on the h2 and not the div further down the DOM tree.

Configuring Scroll Positioning

You can define what it means for an element to 'scroll'. Whether it's the element's scroll position that's changing, its margins or its CSS3 'transform' position, you can define it using the 'scrollProperty' option:

$('#gallery').stellar({
  scrollProperty: 'transform'
});

This option is what allows you to run Stellar.js on iOS.

You can even define how the elements are repositioned, whether it's through standard top and left properties or using CSS3 transforms:

$('#gallery').stellar({
  positionProperty: 'transform'
});

Don't have the level of control you need? Write a plugin!

Otherwise, you're ready to get started!

Configuring Everything

Below you will find a complete list of options and matching default values:

$.stellar({
  // Set scrolling to be in either one or both directions
  horizontalScrolling: true,
  verticalScrolling: true,

  // Set the global alignment offsets
  horizontalOffset: 0,
  verticalOffset: 0,

  // Refreshes parallax content on window load and resize
  responsive: false,

  // Select which property is used to calculate scroll.
  // Choose 'scroll', 'position', 'margin' or 'transform',
  // or write your own 'scrollProperty' plugin.
  scrollProperty: 'scroll',

  // Select which property is used to position elements.
  // Choose between 'position' or 'transform',
  // or write your own 'positionProperty' plugin.
  positionProperty: 'position',

  // Enable or disable the two types of parallax
  parallaxBackgrounds: true,
  parallaxElements: true,

  // Hide parallax elements that move outside the viewport
  hideDistantElements: true,

  // Customise how elements are shown and hidden
  hideElement: function($elem) { $elem.hide(); },
  showElement: function($elem) { $elem.show(); }
});

Writing a Scroll Property Plugin

Out of the box, Stellar.js supports the following scroll properties: 'scroll', 'position', 'margin' and 'transform'.

If your method for creating a scrolling interface isn't covered by one of these, you can write your own. For example, if 'margin' didn't exist yet you could write it like so:

$.stellar.scrollProperty.margin = {
  getLeft: function($element) {
    return parseInt($element.css('margin-left'), 10) * -1;
  },
  getTop: function($element) {
    return parseInt($element.css('margin-top'), 10) * -1;
  }
}

Now, you can specify this scroll property in Stellar.js' configuration.

$.stellar({
  scrollProperty: 'margin'
});

Writing a Position Property Plugin

Stellar.js has two methods for positioning elements built in: 'position' for modifying its top and left properties, and 'transform' for using CSS3 transforms.

If you need more control over how elements are positioned, you can write your own setter functions. For example, if 'position' didn't exist yet, it could be written as a plugin like this:

$.stellar.positionProperty.position = {
  setTop: function($element, newTop, originalTop) {
    $element.css('top', newTop);
  },
  setLeft: function($element, newLeft, originalLeft) {
    $element.css('left', newLeft);
  }
}

Now, you can specify this position property in Stellar.js' configuration.

$.stellar({
  positionProperty: 'position'
});

If, for technical reasons, you need to set both properties at once, you can define a single 'setPosition' function:

$.stellar.positionProperty.foobar = {
  setPosition: function($element, newLeft, originalLeft, newTop, originalTop) {
    $element.css('transform', 'translate3d(' +
      (newLeft - originalLeft) + 'px, ' +
      (newTop - originalTop) + 'px, ' +
      '0)');
  }
}

$.stellar({
  positionProperty: 'foobar'
});

Package Managers

Stellar.js can be installed with Bower:

$ bower install jquery.stellar

Sites Using Stellar.js

I'm sure there are heaps more. Let me know if you'd like me to feature your site here.

How to Build

Stellar.js uses Node.js, Grunt and PhantomJS.

Once you've got Node and PhantomJS set up, install the dependencies:

$ npm install

To lint, test and minify the project, simply run the following command:

$ grunt

Each of the build steps are also available individually.

$ grunt test to test the code using QUnit and PhantomJS:

$ grunt lint to validate the code using JSHint.

$ grunt watch to continuously lint and test the code while developing.

Need help?

As this project is now unmaintained, your best bet is to try the Gitter chat room or Stack Overflow.

License

Copyright 2013, Mark Dalgleish
This content is released under the MIT license
http://markdalgleish.mit-license.org

Comments
  • Doesn't work in Safari / Errors in Chrome console

    Doesn't work in Safari / Errors in Chrome console

    Safari 6.0.4 (8536.29.13):

    TypeError: 'null' is not an object (evaluating 'getComputedStyle($elem[0])[prefixedTransform]') jquery.stellar.js:47
    

    Parallax effect works only on first section. Massive issues if you scroll and then reload the page (try few times): backgrounds appear to be empty. Sometimes all of them, sometimes not.


    Chrome 28.0.1500.29 beta:

    Uncaught TypeError: Cannot read property 'WebkitTransform' of null jquery.stellar.js:47
    

    But still, everything else works fine.


    And if i remove this code from config:

              scrollProperty: 'transform',
              positionProperty: 'transform'
    

    Then scroll runs backwards on both Chrome and Safari. Chrome issue can be fixed by initializing Stellar after browser fully loads page, but i wasn't able to find how to fix it in Safari.


    You can see it here: http://tynkevych.com/ (on production minified version is applied, error preserves) Code: https://github.com/AndrewDryga/tynkevych.com/tree/gh-pages

    opened by AndrewDryga 12
  • Disabling Stellar on Mobile Devices

    Disabling Stellar on Mobile Devices

    So I'm trying to a figure out the best way to disable Stellar for mobile devices, or even disable certain Stellar elements.

    I know there is a tutorial on how to get stellar to work on a webkit based mobile device, however there are some performance issues coming up, and it looks like disabling it all-together is the best way to go.

    I'm looking at using a UA String Regex like this one: www.detectmobilebrowsers.com

    Alternatively, does anyone know what I might be able to check for using Modernizr?

    Thinking forward, perhaps there needs to be a function to disable stellar.js on elements from scrolling. Either set directly on the HTML object or, perhaps a hook that can be initialized from a function or if statement.

    Thanks!

    opened by Giovanni-Mattucci 11
  • avoid jitter without using fixed position

    avoid jitter without using fixed position

    hey,

    I made some parallax animations using stellar.js ... in Chrome everything looks fine but using other browsers there is some heavy jittering (for all elements using a ratio below 1). Looking through the documentation there is written that position: fixed should be used to avoid that ... unfortunately position fixed isn't an option as I would lose the possibility to do relative positioning to the "mother" element. Is there some workaround or do you have some tips how to avoid the stutter without using a fixed position?

    thanks

    opened by m9dfukc 11
  • Stellar and LocalScrollTo

    Stellar and LocalScrollTo

    I am using Stellar along with LocalScroll. I have some images that have a bottom:0 right:0 assigned to them and it seems on the initial page load they are fine and positioned correctly. BTW, stellar assigns top and left values to them, but they are still positioned correctly. Now, if I refresh the page stellar assigns greater values to the top and left causing it not to display correctly. I have only noticed this with elements that initially have right and bottom values. Also looks to only happen in Chrome and IE, FF seems fine.

    opened by x3graphics 8
  • background-position changes randomly after resizing window

    background-position changes randomly after resizing window

    Hi, great work on this plugin, looks promising :) I have got one issue that I haven't been able to fix, and that is with parallax background images, when the responsive option is set to true.

    When the page loads with the browser maximized, then everything displays correctly. But this breaks after resizing the window.

    Resizing will cause the background position to be misplaced because of a randomly changing background-position-y applied to that element. If I try output the background array to console in the refresh() method it seems that the startingbackgroundPosition doesn't get reset when the scroll position is set to zero. So the value tends to change randomly when the window is resized.

    This issue is really easy to reproduce. Just set a background image to an element with data-stellar-background-ratio and responsive: true, then resize the window. Two or three times resizing will cause different background image positions.

    This doesn't happen with particles.

    Is there any way to fix this?

    Thanks

    opened by maimairel 7
  • Can't seem to get this working.

    Can't seem to get this working.

    Hello,

    I cant seem to get this working for me. I am pretty sure I followed the instructions properly.

    Essentially I have 2 background images that need to scroll at different speeds.

    This is what I have: http://jsfiddle.net/QZevq/

    Anyone know what's missing?

    opened by trewknowledge 7
  • Negative Ratio Values

    Negative Ratio Values

    Any suggestions for using negative ratio values?

    I'd like to have one element scrolling in reverse to the others, but the animations become very clunky on iOS.

    opened by matthoiland 7
  • hideDistantElements hides elements when they touch the viewport edges

    hideDistantElements hides elements when they touch the viewport edges

    The setting hideDistantElements: true does hide elements if the top part hits the viewport edge, let them disappear too quickly.

    strange thing is, that I see a different behaviour some times when I reload my page.

    using latest version of stellar (may5th) and chrome 19.

    example (in progress): http://clients.nordsueddesign.de/hdk.ch/

    —Johannes

    opened by johanneseckert 6
  • Allow for different horizontal and vertical ratios

    Allow for different horizontal and vertical ratios

    I've added in the ability for have different horizontal and vertical ratios to allow for tighter control over the animations for weird scenarios.

    They take values from data-stellar-horizontal-ratio and data-stellar-vertical-ratio, falling back to the original data-stellar-ratio, and finally back to 1 as in the original code.

    opened by iblamefish 6
  • Reposition/Reinitialise

    Reposition/Reinitialise

    Hey Mark,

    Loving this plugin! Is there any way to quickly reinitialise Stellar in the page?

    I'm using Stellar for a vertical scrolling site and I've noticed that it seems to work fine for a fluid width page, but I'm also using JS to change the heights of some parent elements from time to time (screen resizing thing), which seems to make it go funny. I tried destroying and calling the plugin again but that didn't seem to work, it just remained destroyed.

    It would be great if there was some sort of reposition method that just quickly reinitialised the whole thing, would this be tricky to implement?

    opened by funwithtriangles 5
  • Anyone got the stellar.js working in IE 8 ?

    Anyone got the stellar.js working in IE 8 ?

    It looks like the parallax effect is disabled in IE 7-8, but works well in IE 9. Just checking in if anybody were able to make it works before I investigate a bit further.

    Thank you

    opened by allaire 5
  • Changing page height breaks positioning of background

    Changing page height breaks positioning of background

    With something like an accordion which changes the height of the viewport should the plugin not act like a window resize?

    Currently if the viewport changes height due to an expanding element it breaks the parallax as the calculations are based on the original viewport height

    opened by quantumwebco 0
  • jquery 3.2.1 -  boostrap v4  plugin not working

    jquery 3.2.1 - boostrap v4 plugin not working

    I'm trying to use stellar with bootstrap v4, jquery 3.2.1 but it returns error "Uncaught TypeError: elem.getClientRects is not a function"

    https://jsfiddle.net/farkasimre/fo2pba5o/

    Thanks!

    opened by farkasimre 1
  • Element missing when first time loading page

    Element missing when first time loading page

    One of parallax image is missing while scrolling when i load the webpage for the first time. When I scroll down, the element just vanishes. After I reload the page again, everything works perfectly just fine. supahands parallax bug

    Anyone else having the same issue?

    opened by baimhanifkamil 3
  • Can we have ES6 support for stellar?

    Can we have ES6 support for stellar?

    This is the robust & easiest parallax that I found. The only problem I got that is stellar not work with es6. I tried many ways but no hope.

    Can we have ES6 support for stellar?

    opened by bnqtoan 2
Owner
Mark Dalgleish
CSS Modules co-creator, Playroom, Braid, MelbJS. OSS / UI / design / tooling at @seek-oss
Mark Dalgleish
🛤 Detection of elements in viewport & smooth scrolling with parallax.

Locomotive Scroll Detection of elements in viewport & smooth scrolling with parallax effects. Installation ⚠️ Scroll-hijacking is a controversial prac

Locomotive 5.9k Dec 31, 2022
Parallax Engine that reacts to the orientation of a smart device

Parallax Engine that reacts to the orientation of a smart device. Where no gyroscope or motion detection hardware is available, the position of the cu

Matthew Wagerfield 16k Jan 8, 2023
jQuery plugin for creating interactive parallax effect

jquery.parallax What does jquery.parallax do? jquery.parallax turns nodes into absolutely positioned layers that move in response to the mouse. Depend

stephband 1.1k Nov 25, 2022
Simple and tiny JavaScript library that adds parallax animations on any images

simpleParallax.js simpleParallax.js is a very simple and tiny Vanilla JS library that adds parallax animations on any images. Where it may be laboriou

Geoffrey 1.5k Jan 3, 2023
Lightweight, vanilla javascript parallax library

RELLAX Rellax is a buttery smooth, super lightweight, vanilla javascript parallax library. Update: Rellax now works on mobile (v1.0.0). Demo Website G

Dixon & Moe 6.7k Dec 30, 2022
Smooth scrolling for the web

iScroll, smooth scrolling for the web iScroll is a high performance, small footprint, dependency free, multi-platform javascript scroller. It works on

Matteo Spinelli 12.9k Jan 4, 2023
Dragscroll is a micro library for drag-n-drop scrolling style

Dragscroll is a micro JavaScript library (910 bytes minified) which enables scrolling via holding the mouse button ("drag and drop" or "click and hold" style, online demo). It has no dependencies and is written in vanilla JavaScript (which means it works anywhere).

Dmitry Prokashev 1.1k Dec 21, 2022
BetterScroll is a plugin which is aimed at solving scrolling circumstances on the mobile side (PC supported already).

BetterScroll is a plugin which is aimed at solving scrolling circumstances on the mobile side (PC supported already).

HuangYi 15.9k Dec 30, 2022
Scroll made easy!

Demo - Installation - Methods - Callbacks - Styling ◼️ Features: ?? Native Scroll Behavior ?? Standardized events / shortcuts / API ?? Fast & Lightwei

Bruno Vieira 307 Nov 20, 2022
Stand-alone parallax scrolling library for mobile (Android + iOS) and desktop. No jQuery. Just plain JavaScript (and some love).

Please note: skrollr hasn't been under active development since about September 2014 (check out the contributions graphs on https://github.com/Prinzho

Alexander Prinzhorn 18.6k Jan 3, 2023
Simple parallax scrolling effect inspired by Spotify.com implemented as a jQuery plugin

Parallax.js Simple parallax scrolling implemented as a jQuery plugin. http://pixelcog.com/parallax.js/ Please also check our v2.0.0-alpha! We'd be hap

PixelCog Inc. 3.5k Dec 21, 2022
Slickscroll - A Lightweight JavaScript library for quick and painless momentum & parallax scrolling effects.

Slickscroll is a JavaScript library that makes momentum & parallax scrolling quick and painless View Demo: slickscroll.musabhassan.com Momentum Scroll

Musab Hassan 33 Dec 28, 2022
🛤 Detection of elements in viewport & smooth scrolling with parallax.

Locomotive Scroll Detection of elements in viewport & smooth scrolling with parallax effects. Installation ⚠️ Scroll-hijacking is a controversial prac

Locomotive 5.9k Dec 31, 2022
Seamless and lightweight parallax scrolling library implemented in pure JavaScript utilizing Hardware acceleration for extra performance.

parallax-vanilla.js Seamless and lightweight parallax scrolling library implemented in pure JavaScript utilizing Hardware acceleration for extra perfo

Erik Engervall 91 Dec 16, 2022
Parallax scrolling jQuery plugin

paroller.js A lightweight jQuery plugin that enables parallax scrolling effect You can use it on elements with background property or on any other ele

null 579 Dec 26, 2022
Sharing the latest stellar Super Mario 64 runs verified on speedrun.com.

SM64-twitter-bot Sharing the latest stellar Super Mario 64 runs verified on speedrun.com. https://twitter.com/SuperMario64Bot Requirements You will ne

hippolyte 4 Jul 14, 2022
jQuery based scrolling Bar, for PC and Smartphones (touch events). It is modern slim, easy to integrate, easy to use. Tested on Firefox/Chrome/Maxthon/iPhone/Android. Very light <7ko min.js and <1Ko min.css.

Nice-Scrollbar Responsive jQuery based scrolling Bar, for PC and Smartphones (touch events). It is modern slim, easy to integrate, easy to use. Tested

Renan LAVAREC 2 Jan 18, 2022
Parallax Engine that reacts to the orientation of a smart device

Parallax Engine that reacts to the orientation of a smart device. Where no gyroscope or motion detection hardware is available, the position of the cu

Matthew Wagerfield 16k Jan 8, 2023
jQuery plugin for creating interactive parallax effect

jquery.parallax What does jquery.parallax do? jquery.parallax turns nodes into absolutely positioned layers that move in response to the mouse. Depend

stephband 1.1k Nov 25, 2022
Simple and tiny JavaScript library that adds parallax animations on any images

simpleParallax.js simpleParallax.js is a very simple and tiny Vanilla JS library that adds parallax animations on any images. Where it may be laboriou

Geoffrey 1.5k Jan 3, 2023