` js
$('#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:

` js
$('#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:

` js
$.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:

` js
$.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.

` js
$.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:

` js
$.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.

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

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

` js
$.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:

` bash
$ bower install jquery.stellar
`

Sites Using Stellar.js

* National Geographic - Alien Deep Interactive
* François Hollande
* Brabus Private Aviation
* Mary and Frankie's Wedding
* IT Support London
* Ashford University
* Clif Adventures
* Mindster
* WS Interactive
* Moire Mag - Untitled
* Carnival of Courage
* Ian Poulter
* 360 Strategy Group
* Code, Love and Boards

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