You are on page 1of 4

Getting Started

Stellar.js is a jQuery plugin that provides parallax scrolling effects to any sc


rolling 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 ele
ment and reposition them when the element scrolls.
Mobile Support
Support in Mobile WebKit browsers requires a touch scrolling library, and a slig
htly tweaked configuration. For a full walkthrough on how to implement this corr
ectly, read my blog post "Mobile Parallax with Stellar.js".
Please note that parallax backgrounds are not recommended in Mobile WebKit, only
parallax elements.
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 r
atio 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 it
s CSS position to fixed.
Parallax Backgrounds
If you want an element's background image to reposition on scroll, simply add th
e following attribute:
<div data-stellar-background-ratio="0.5">
As with parallax elements, the ratio is relative to the natural scroll speed. Fo
r ratios lower than 1, to avoid jittery scroll performance, set the element's CS
S '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 y
ou 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 th
e way an absolutely positioned element behaves when nested inside an element wit
h a relative position.
As with regular CSS, the closest parent element with a position of relative or a
bsolute 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 Jav
aScript 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 h
ow the alignment happens on a per-letter basis? That's because each letter's con
taining div is its default offset parent.
By specifying the h2 element as the offset parent, we can ensure that the alignm
ent of all the stars in a heading is based on the h2 and not the div further dow
n the DOM tree.
Configuring Scroll Positioning
You can define what it means for an element to 'scroll'. Whether it's the elemen
t's scroll position that's changing, its margins or its CSS3 'transform' positio
n, 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 stan
dard 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 wri
te 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 mod
ifying 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 ow
n setter functions. For example, if 'position' didn't exist yet, it could be wri
tten 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 defi
ne a single 'setPosition' function:
$.stellar.positionProperty.foobar = {
setPosition: function($el, x, startX, y, startY) {
$el.css('transform', 'translate3d(' +
(x - startX) + 'px, ' +
(y - startY) + 'px, ' +
'0)');
}
}
$.stellar({
positionProperty: 'foobar'
});
Questions