ScrollMagic

Class: ScrollScene

ScrollScene

new ScrollScene(options)

A ScrollScene defines where the controller should react and how.

Parameters:
Name Type Argument Description
options object <optional>

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:
Example
// create a standard scene and add it to a controllernew 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 <optional>

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:
Example
// add basic indicatorsscene.addIndicators()// passing optionsscene.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:
Returns:

Parent object for chaining.

{ ScrollScene }
Example
// add a scene to a ScrollMagic controllerscene.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:
Returns:

Null to unset handler variables.

{ null }
Example
// destroy the scene without resetting the pin and tween to their initial positionsscene = scene.destroy();// destroy the scene and reset the pin and tweenscene = 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:
Fires:
Returns:

  • get - Current scene duration.

    { number }

  • set - Parent object for chaining.

    { ScrollScene }
Example
// get the current duration valuevar duration = scene.duration();// set a new durationscene.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:
Returns:

Current enabled state or parent object for chaining.

{ boolean | ScrollScene }
Example
// get the current valuevar enabled = scene.enabled();// disable the scenescene.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:
Fires:
Returns:

  • get - Current loglevel.

    { number }

  • set - Parent object for chaining.

    { ScrollScene }
Example
// get the current loglevelvar loglevel = scene.loglevel();// set new loglevelscene.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:
Returns:

Parent object for chaining.

{ ScrollScene }
Example
function callback (event) {		console.log("Event fired! (" + event.type + ")");}// add listenersscene.on("change update", callback);// remove listenersscene.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:
Fires:
Returns:

  • get - Current scene offset.

    { number }

  • set - Parent object for chaining.

    { ScrollScene }
Example
// get the current offsetvar offset = scene.offset();// set a new offsetscene.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:
Returns:

Parent object for chaining.

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

parent() → {ScrollMagic}

Get the parent controller.

Source:
Returns:

Parent controller or undefined

{ ScrollMagic }
Example
// get the parent controller of a scenevar 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:
Fires:
Returns:

  • get - Current scene progress.

    { number }

  • set - Parent object for chaining.

    { ScrollScene }
Example
// get the current scene progressvar progress = scene.progress();// set new scene progressscene.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:
Returns:

Parent object for chaining.

{ ScrollScene }
Example
// remove the scene from its parent controllerscene.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:
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:
Returns:

Parent object for chaining.

{ ScrollScene }
Example
// remove the tween from the scene without resetting itscene.removeTween();// remove the tween from the scene and reset it to initial positionscene.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:
Fires:
Returns:

  • get - Current reverse option value.

    { boolean }

  • set - Parent object for chaining.

    { ScrollScene }
Example
// get the current reverse optionvar reverse = scene.reverse();// set new reverse optionscene.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:
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 <optional>

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:
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:
Returns:

Parent object for chaining.

{ ScrollScene }
Example
// add a single tweenscene.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:

    state() → {string}

    Get the current state.

    Source:
    Returns:

    "BEFORE", "DURING" or "AFTER"

    { string }
    Example
    // get the current statevar 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:
    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:
    Fires:
    Returns:

    • get - Current triggerElement.

      { string | object }

    • set - Parent object for chaining.

      { ScrollScene }
    Example
    // get the current triggerElementvar triggerElement = scene.triggerElement();// set a new triggerElement using a selectorscene.triggerElement("#trigger");// set a new triggerElement using a jQuery Objectscene.triggerElement($("#trigger"));// set a new triggerElement using a DOM Objectscene.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:
    Fires:
    Returns:

    • get - Current triggerHook (ALWAYS numerical).

      { number }

    • set - Parent object for chaining.

      { ScrollScene }
    Example
    // get the current triggerHook valuevar triggerHook = scene.triggerHook();// set a new triggerHook using a stringscene.triggerHook("onLeave");// set a new triggerHook using a numberscene.triggerHook(0.7);

    triggerOffset() → {number}

    Get the trigger offset of the scene.

    Source:
    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 offsetvar 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:
    Fires:
    Returns:

    • get - Current tweenChanges option value.

      { boolean }

    • set - Parent object for chaining.

      { ScrollScene }
    Example
    // get the current tweenChanges optionvar tweenChanges = scene.tweenChanges();// set new tweenChanges optionscene.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:
    Fires:
    Returns:

    Parent object for chaining.

    { ScrollScene }
    Example
    // update the scene on next tickscene.update();// update the scene immediatelyscene.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:
    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:
    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:
    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:
    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:
    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:
    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:
    Example
    scene.on("update", function (event) {		console.log("Scene updated.");});