ScrollMagic Class: ScrollScene

new ScrollScene(options)

A ScrollScene defines where the controller should react and how.

Parameters:

Name Type Argument Description

options

object

Options for the Scene. The options can be updated at any time.
Instead of setting the options for each scene individually you can also set them globally in the controller as the controllers globalSceneOptions option. The object accepts the same properties as the ones below.
When a scene is added to the controller the options defined using the ScrollScene constructor will be overwritten by those set in globalSceneOptions.

Properties

Name	Type	Argument	Default	Description
`duration`	number	<optional>	0	The duration of the scene. If `0` tweens will auto-play when reaching the scene start point, pins will be pinned indefinetly starting at the start position.
`offset`	number	<optional>	0	Offset Value for the Trigger Position. If no triggerElement is defined this will be the scroll distance from the start of the page, after which the scene will start.
`triggerElement`	string \| object	<optional>	null	Selector, DOM Object or jQuery Object that defines the start of the scene. If undefined the scene will start right at the start of the page (unless an offset is set).
`triggerHook`	number \| string	<optional>	"onCenter"	Can be a number between 0 and 1 defining the position of the trigger Hook in relation to the viewport. Can also be defined using a string: `"onEnter"` => `1` `"onCenter"` => `0.5` `"onLeave"` => `0`
`reverse`	boolean	<optional>	true	Should the scene reverse, when scrolling up?
`tweenChanges`	boolean	<optional>	false	Tweens Animation to the progress target instead of setting it. Does not affect animations where duration is `0`.
`loglevel`	number	<optional>	2	Loglevel for debugging. `0` => silent `1` => errors `2` => errors, warnings `3` => errors, warnings, debuginfo

Source:

jquery.scrollmagic.js, line 588

Example

// create a standard scene and add it to a controller
new ScrollScene()
		.addTo(controller);

// create a scene with custom options and assign a handler to it.
var scene = new ScrollScene({
		duration: 100,
		offset: 200,
		triggerHook: "onEnter",
		reverse: false
});

Methods

addIndicators(options)

Add Indicators for a ScrollScene.
REQUIRES ScrollMagic Debug Extension: jquery.scrollmagic.debug.js
The indicators can only be added AFTER the scene has been added to a controller.

Parameters:

Name Type Argument Description

options

object

An object containing one or more options for the indicators.

Properties

Name	Type	Argument	Default	Description
`parent`	string \| object	<optional>	undefined	A selector, DOM Object or a jQuery object that the indicators should be added to. If undefined, the scene's container will be used.
`zindex`	number	<optional>	-1	CSS zindex for the indicator container.
`indent`	number	<optional>	0	Additional position offset for the indicators (useful, when having multiple scenes starting at the same time).
`suffix`	number	<optional>	""	This string will be attached to the start and end indicator (useful for identification when working with multiple scenes).
`colorTrigger`	string	<optional>	blue	CSS color definition for the trigger indicator.
`colorStart`	string	<optional>	green	CSS color definition for the start indicator.
`colorEnd`	string	<optional>	red	CSS color definition for the end indicator.

Source:

jquery.scrollmagic.debug.js, line 43

Example

// add basic indicators
scene.addIndicators()

// passing options
scene.addIndicators({zindex: 100, colorEnd: "#FFFFFF"});

addTo(controller) → {ScrollScene}

Add the scene to a controller.
This is the equivalent to ScrollMagic.addScene(scene).

Parameters:

Name	Type	Description
`controller`	ScrollMagic	The controller to which the scene should be added.

Source:

jquery.scrollmagic.js, line 1627

Returns:

Parent object for chaining.

{ ScrollScene }

Example

// add a scene to a ScrollMagic controller
scene.addTo(controller);

destroy(reset) → {null}

Destroy the scene and everything.

Parameters:

Name	Type	Argument	Default	Description
`reset`	boolean	<optional>	false	If `true` the pin and tween (if existent) will be reset.

Source:

jquery.scrollmagic.js, line 1706

Returns:

Null to unset handler variables.

{ null }

Example

// destroy the scene without resetting the pin and tween to their initial positions
scene = scene.destroy();

// destroy the scene and reset the pin and tween
scene = scene.destroy(true);

duration(newDuration) → {number}

Get or Set the duration option value.

Parameters:

Name	Type	Argument	Description
`newDuration`	number	<optional>	The new duration of the scene.

Source:

jquery.scrollmagic.js, line 994

Fires:

ScrollScene.event:change, when used as setter

Returns:

get - Current scene duration.
{ number }
set - Parent object for chaining.
{ ScrollScene }

Example

// get the current duration value
var duration = scene.duration();

// set a new duration
scene.duration(300);

enabled(newState) → {boolean|ScrollScene}

Get or Set the current enabled state of the scene.
This can be used to disable this scene without removing or destroying it.

Parameters:

Name	Type	Argument	Description
`newState`	boolean	<optional>	The new enabled state of the scene `true` or `false`.

Source:

jquery.scrollmagic.js, line 1660

Returns:

Current enabled state or parent object for chaining.

{ boolean | ScrollScene }

Example

// get the current value
var enabled = scene.enabled();

// disable the scene
scene.enabled(false);

loglevel(newLoglevel) → {number}

Get or Set the loglevel option value.

Parameters:

Name	Type	Argument	Description
`newLoglevel`	number	<optional>	The new loglevel setting of the scene. `[0-3]`

Source:

jquery.scrollmagic.js, line 1168

Fires:

ScrollScene.event:change, when used as setter

Returns:

get - Current loglevel.
{ number }
set - Parent object for chaining.
{ ScrollScene }

Example

// get the current loglevel
var loglevel = scene.loglevel();

// set new loglevel
scene.loglevel(3);

off(name, callback) → {ScrollScene}

Remove one or more event listener.

Parameters:

Name	Type	Argument	Description
`name`	string		The name or names of the event that should be removed.
`callback`	function	<optional>	A specific callback function that should be removed. If none is passed all callbacks to the event listener will be removed.

Source:

jquery.scrollmagic.js, line 1896

Returns:

Parent object for chaining.

{ ScrollScene }

Example

function callback (event) {
		console.log("Event fired! (" + event.type + ")");
}
// add listeners
scene.on("change update", callback);
// remove listeners
scene.off("change update", callback);

offset(newOffset) → {number}

Get or Set the offset option value.

Parameters:

Name	Type	Argument	Description
`newOffset`	number	<optional>	The new offset of the scene.

Source:

jquery.scrollmagic.js, line 1019

Fires:

ScrollScene.event:change, when used as setter

Returns:

get - Current scene offset.
{ number }
set - Parent object for chaining.
{ ScrollScene }

Example

// get the current offset
var offset = scene.offset();

// set a new offset
scene.offset(100);

on(name, callback) → {ScrollScene}

Add one ore more event listener.
The callback function will be fired at the respective event, and an object containing relevant data will be passed to the callback.

Parameters:

Name	Type	Description
`name`	string	The name or names of the event the callback should be attached to.
`callback`	function	A function that should be executed, when the event is dispatched. An event object will be passed to the callback.

Source:

jquery.scrollmagic.js, line 1867

Returns:

Parent object for chaining.

{ ScrollScene }

Example

function callback (event) {
		console.log("Event fired! (" + event.type + ")");
}
// add listeners
scene.on("change update progress start end enter leave", callback);

parent() → {ScrollMagic}

Get the parent controller.

Source:

jquery.scrollmagic.js, line 974

Returns:

Parent controller or undefined

{ ScrollMagic }

Example

// get the parent controller of a scene
var controller = scene.parent();

progress(progress) → {number}

Get or Set the scene's progress.
Usually it shouldn't be necessary to use this as a setter, as it is set automatically by scene.update().

Parameters:

Name	Type	Argument	Description
`progress`	number	<optional>	The new progress value of the scene `[0-1]`.

Source:

jquery.scrollmagic.js, line 1337

Fires:

ScrollScene.event:enter, when used as setter
ScrollScene.event:start, when used as setter
ScrollScene.event:progress, when used as setter
ScrollScene.event:end, when used as setter
ScrollScene.event:leave, when used as setter

Returns:

get - Current scene progress.
{ number }
set - Parent object for chaining.
{ ScrollScene }

Example

// get the current scene progress
var progress = scene.progress();

// set new scene progress
scene.progress(0.3);

remove() → {ScrollScene}

Remove the scene from its parent controller.
This is the equivalent to ScrollMagic.removeScene(scene). The scene will not be updated anymore until you readd it to a controller. To remove the pin or the tween you need to call removeTween() or removePin() respectively.

Source:

jquery.scrollmagic.js, line 1682

Returns:

Parent object for chaining.

{ ScrollScene }

Example

// remove the scene from its parent controller
scene.remove();

removePin(reset) → {ScrollScene}

Remove the pin from the scene.

Parameters:

Name	Type	Argument	Default	Description
`reset`	boolean	<optional>	false	If `false` the spacer will not be removed and the element's position will not be reset.

Source:

jquery.scrollmagic.js, line 1598

Returns:

Parent object for chaining.

{ ScrollScene }

Example

// remove the pin from the scene without resetting it (the spacer is not removed)
scene.removePin();

// remove the pin from the scene and reset the pin element to its initial position (spacer is removed)
scene.removePin(true);

removeTween(reset) → {ScrollScene}

Remove the tween from the scene.

Parameters:

Name	Type	Argument	Default	Description
`reset`	boolean	<optional>	false	If `true` the tween will be reset to its initial values.

Source:

jquery.scrollmagic.js, line 1451

Returns:

Parent object for chaining.

{ ScrollScene }

Example

// remove the tween from the scene without resetting it
scene.removeTween();

// remove the tween from the scene and reset it to initial position
scene.removeTween(true);

reverse(newReverse) → {boolean}

Get or Set the reverse option value.

Parameters:

Name	Type	Argument	Description
`newReverse`	boolean	<optional>	The new reverse setting of the scene.

Source:

jquery.scrollmagic.js, line 1118

Fires:

ScrollScene.event:change, when used as setter

Returns:

get - Current reverse option value.
{ boolean }
set - Parent object for chaining.
{ ScrollScene }

Example

// get the current reverse option
var reverse = scene.reverse();

// set new reverse option
scene.reverse(false);

scrollOffset() → {number}

Get the current scroll offset for the start of the scene.
Mind, that the scrollOffset is related to the size of the container, if triggerHook is bigger than 0 (or "onLeave").
This means, that resizing the container will influence the scene's start offset.

Source:

jquery.scrollmagic.js, line 1256

Returns:

The scroll offset (of the container) at which the scene will trigger. Y value for vertical and X value for horizontal scrolls.

{ number }

Example

// get the current scroll offset for the start and end of the scene.
var start = scene.scrollOffset();
var end = scene.scrollOffset() + scene.duration();
console.log("the scene starts at", start, "and ends at", end);

setPin(element, settings) → {ScrollScene}

Pin an element for the duration of the tween.
If the scene duration is 0 the element will never be unpinned.
Note, that pushFollowers has no effect, when the scene duration is 0.

Parameters:

Name Type Argument Description

element

string | object

A Selctor, a DOM Object or a jQuery object for the object that is supposed to be pinned.

settings

object

settings for the pin

Properties

Name	Type	Argument	Default	Description
`pushFollowers`	boolean	<optional>	true	If `true` following elements will be "pushed" down for the duration of the pin, if `false` the pinned element will just scroll past them. Ignored, when duration is `0`.
`spacerClass`	string	<optional>	"scrollmagic-pin-spacer"	Classname of the pin spacer element, which is used to replace the element.
`pinnedClass`	string	<optional>	""	Classname that should be added to the pinned element during pin phase (and removed after).

Source:

jquery.scrollmagic.js, line 1484

Returns:

Parent object for chaining.

{ ScrollScene }

Example

// pin element and push all following elements down by the amount of the pin duration.
scene.setPin("#pin");

// pin element and keeping all following elements in their place. The pinned element will move past them.
scene.setPin("#pin", {pushFollowers: false});

setTween(TweenMaxObject) → {ScrollScene}

Add a tween to the scene.
If you want to add multiple tweens, wrap them into one TimelineMax object and add it.
The duration of the tween is streched to the scroll duration of the scene, unless the scene has a duration of 0.

Parameters:

Name	Type	Description
`TweenMaxObject`	object	A TweenMax, TweenLite, TimelineMax or TimelineLite object that should be animated in the scene.

Source:

jquery.scrollmagic.js, line 1412

Returns:

Parent object for chaining.

{ ScrollScene }

Example

// add a single tween
scene.setTween(TweenMax.to("obj"), 1, {x: 100});

// add multiple tweens, wrapped in a timeline.
var timeline = new TimelineMax();
var tween1 = TweenMax.from("obj1", 1, {x: 100});
var tween2 = TweenMax.to("obj2", 1, {y: 100});
timeline
		.add(tween1)
		.add(tween2);
scene.addTween(timeline);

startPosition()

Get the trigger offset of the scene.

Deprecated:

Method is deprecated since 1.0.7. You should now use ScrollScene.triggerOffset

Source:

jquery.scrollmagic.js, line 1196

state() → {string}

Get the current state.

Source:

jquery.scrollmagic.js, line 1187

Returns:

"BEFORE", "DURING" or "AFTER"

{ string }

Example

// get the current state
var state = scene.state();

trigger(name, vars) → {ScrollScene}

Trigger an event.

Parameters:

Name	Type	Argument	Description
`name`	string		The name of the event that should be triggered.
`vars`	object	<optional>	An object containing info that should be passed to the callback.

Source:

jquery.scrollmagic.js, line 1915

Returns:

Parent object for chaining.

{ ScrollScene }

Example

this.trigger("change");

triggerElement(newTriggerElement) → {string|object}

Get or Set the triggerElement option value.

Parameters:

Name	Type	Argument	Description
`newTriggerElement`	string \| object	<optional>	The new trigger element for the scene.

Source:

jquery.scrollmagic.js, line 1048

Fires:

ScrollScene.event:change, when used as setter

Returns:

get - Current triggerElement.
{ string | object }
set - Parent object for chaining.
{ ScrollScene }

Example

// get the current triggerElement
var triggerElement = scene.triggerElement();

// set a new triggerElement using a selector
scene.triggerElement("#trigger");
// set a new triggerElement using a jQuery Object
scene.triggerElement($("#trigger"));
// set a new triggerElement using a DOM Object
scene.triggerElement(document.getElementById("trigger"));

triggerHook(newTriggerHook) → {number}

Get or Set the triggerHook option value.

Parameters:

Name	Type	Argument	Description
`newTriggerHook`	number \| string	<optional>	The new triggerHook of the scene. See `ScrollScene` parameter description for value options.

Source:

jquery.scrollmagic.js, line 1075

Fires:

ScrollScene.event:change, when used as setter

Returns:

get - Current triggerHook (ALWAYS numerical).
{ number }
set - Parent object for chaining.
{ ScrollScene }

Example

// get the current triggerHook value
var triggerHook = scene.triggerHook();

// set a new triggerHook using a string
scene.triggerHook("onLeave");
// set a new triggerHook using a number
scene.triggerHook(0.7);

triggerOffset() → {number}

Get the trigger offset of the scene.

Source:

jquery.scrollmagic.js, line 1209

Returns:

Start position of the scene. Top position value for vertical and left position value for horizontal scrolls.

{ number }

Example

// get the scene's trigger offset
var triggerOffset = scene.triggerOffset();

tweenChanges(newTweenChanges) → {boolean}

Get or Set the tweenChanges option value.

Parameters:

Name	Type	Argument	Description
`newTweenChanges`	boolean	<optional>	The new tweenChanges setting of the scene.

Source:

jquery.scrollmagic.js, line 1143

Fires:

ScrollScene.event:change, when used as setter

Returns:

get - Current tweenChanges option value.
{ boolean }
set - Parent object for chaining.
{ ScrollScene }

Example

// get the current tweenChanges option
var tweenChanges = scene.tweenChanges();

// set new tweenChanges option
scene.tweenChanges(true);

update(immediately) → {ScrollScene}

Updates the Scene in the parent Controller to reflect the current state.
This is the equivalent to ScrollMagic.updateScene(scene, immediately).
The update method calculates the scene's start and end position (based on the trigger element, trigger hook, duration and offset) and checks it against the current scroll position of the container.
It then updates the current scene state accordingly (or does nothing, if the state is already correct) – Pins will be set to their correct position and tweens will be updated to their correct progress.
Note: This method gets called constantly whenever ScrollMagic detects a change. The only application for you is if you change something outside of the realm of ScrollMagic, like moving the trigger or changing tween parameters.

Parameters:

Name	Type	Argument	Default	Description
`immediately`	boolean	<optional>	false	If `true` the update will be instant, if `false` it will wait until next tweenmax tick (better performance).

Source:

jquery.scrollmagic.js, line 1285

Fires:

ScrollScene.event:update

Returns:

Parent object for chaining.

{ ScrollScene }

Example

// update the scene on next tick
scene.update();

// update the scene immediately
scene.update(true);

Events

change

Scene change event.
Fires whenvever a property of the scene is changed.

Properties:

Name Type Description

event

object

The event Object passed to each callback

Properties

Name	Type	Description
`type`	string	The name of the event
`target`	ScrollScene	The ScrollScene object that triggered this event
`what`	string	Indicates what value has been changed
`newval`	mixed	The new value of the changed property

Source:

jquery.scrollmagic.js, line 1833

Example

scene.on("change", function (event) {
		console.log("Scene Property \"" + event.what + "\" changed to " + event.newval);
});

end

Scene end event.
Fires whenever the scroll position its the ending point of the scene.
It will also fire when scrolling back up from after the scene and going over its end position. If you want something to happen only when scrolling down/right, use the scrollDirection parameter passed to the callback.

Properties:

Name Type Description

event

object

The event Object passed to each callback

Properties

Name	Type	Description
`type`	string	The name of the event
`target`	ScrollScene	The ScrollScene object that triggered this event
`progress`	number	Reflects the current progress of the scene
`state`	string	The current state of the scene `"BEFORE"`, `"DURING"` or `"AFTER"`
`scrollDirection`	string	Indicates which way we are scrolling `"PAUSED"`, `"FORWARD"` or `"REVERSE"`

Source:

jquery.scrollmagic.js, line 1740

Example

scene.on("end", function (event) {
		alert("Hit end point of scene.");
});

enter

Scene enter event.
Fires whenever the scene enters the "DURING" state.
Keep in mind that it doesn't matter if the scene plays forward or backward: This event always fires when the scene enters its active scroll timeframe, regardless of the scroll-direction.

Properties:

Name Type Description

event

object

The event Object passed to each callback

Properties

Name	Type	Description
`type`	string	The name of the event
`target`	ScrollScene	The ScrollScene object that triggered this event
`progress`	number	Reflects the current progress of the scene
`state`	string	The current state of the scene `"BEFORE"`, `"DURING"` or `"AFTER"`
`scrollDirection`	string	Indicates which way we are scrolling `"PAUSED"`, `"FORWARD"` or `"REVERSE"`

Source:

jquery.scrollmagic.js, line 1759

Example

scene.on("enter", function (event) {
		alert("Entered a scene.");
});

leave

Scene leave event.
Fires whenever the scene's state goes from "DURING" to either "BEFORE" or "AFTER".
Keep in mind that it doesn't matter if the scene plays forward or backward: This event always fires when the scene leaves its active scroll timeframe, regardless of the scroll-direction.

Properties:

Name Type Description

event

object

The event Object passed to each callback

Properties

Name	Type	Description
`type`	string	The name of the event
`target`	ScrollScene	The ScrollScene object that triggered this event
`progress`	number	Reflects the current progress of the scene
`state`	string	The current state of the scene `"BEFORE"`, `"DURING"` or `"AFTER"`
`scrollDirection`	string	Indicates which way we are scrolling `"PAUSED"`, `"FORWARD"` or `"REVERSE"`

Source:

jquery.scrollmagic.js, line 1778

Example

scene.on("leave", function (event) {
		alert("Left a scene.");
});

progress

Scene progress event.
Fires whenever the progress of the scene changes.

Properties:

Name Type Description

event

object

The event Object passed to each callback

Properties

Name	Type	Description
`type`	string	The name of the event
`target`	ScrollScene	The ScrollScene object that triggered this event
`progress`	number	Reflects the current progress of the scene
`state`	string	The current state of the scene `"BEFORE"`, `"DURING"` or `"AFTER"`
`scrollDirection`	string	Indicates which way we are scrolling `"PAUSED"`, `"FORWARD"` or `"REVERSE"`

Source:

jquery.scrollmagic.js, line 1815

Example

scene.on("progress", function (event) {
		console.log("Scene progress changed.");
});

start

Scene start event.
Fires whenever the scroll position its the starting point of the scene.
It will also fire when scrolling back up going over the start position of the scene. If you want something to happen only when scrolling down/right, use the scrollDirection parameter passed to the callback.

Properties:

Name Type Description

event

object

The event Object passed to each callback

Properties

Name	Type	Description
`type`	string	The name of the event
`target`	ScrollScene	The ScrollScene object that triggered this event
`progress`	number	Reflects the current progress of the scene
`state`	string	The current state of the scene `"BEFORE"`, `"DURING"` or `"AFTER"`
`scrollDirection`	string	Indicates which way we are scrolling `"PAUSED"`, `"FORWARD"` or `"REVERSE"`

Source:

jquery.scrollmagic.js, line 1721

Example

scene.on("start", function (event) {
		alert("Hit start point of scene.");
});

update

Scene update event.
Fires whenever the scene is updated (but not necessarily changes the progress).

Properties:

Name Type Description

event

object

The event Object passed to each callback

Properties

Name	Type	Description
`type`	string	The name of the event
`target`	ScrollScene	The ScrollScene object that triggered this event
`startPos`	number	The starting position of the scene (in relation to the conainer)
`endPos`	number	The ending position of the scene (in relation to the conainer)
`scrollPos`	number	The current scroll position of the container

Source:

jquery.scrollmagic.js, line 1797

Example

scene.on("update", function (event) {
		console.log("Scene updated.");
});