Skip to main content

set

set( target:[ Object | Array | String ], vars:Object, position:[ Number | String ] ) : self

Adds a zero-duration tween to the end of the timeline (or elsewhere using the position parameter) that sets values immediately when the virtual playhead reaches that position on the timeline - this is a convenience method that accomplishes exactly the same thing as add( gsap.to(target, {duration: 0, ...}) ) but with less code.

Parameters

  • target: [ Object | Array | String ]

    Target object (or array of objects) whose properties will be set.

  • vars: Object

    An object defining the value to which each property should be set. For example, to set element's left to 100 and element's top to 200, do this:myTimeline.set(element, {left: 100, top: 200});

  • position: [ Number | String ]

    (default = "+=0") - controls the insertion point in the timeline (by default, it's the end of the timeline). See options below, or the Position Parameter article which has interactive timeline visualizations and a video. If you define a label that doesn't exist yet, it will automatically be added to the end of the timeline

Returns : self​

self (makes chaining easier)

Details​

Adds a gsap.set() to the end of the timeline (or elsewhere using the "position" parameter) - this is a convenience method that accomplishes exactly the same thing as add( gsap.set(...) ) but with less code. For example:

var tl = gsap.timeline();

var setValues = gsap.set(element, { x: 100, opacity: 0.5 });
tl.add(setValues);

//this line produces the same result as the previous two lines (just shorter)
tl.set(element, { x: 100, opacity: 0.5 });

See the gsap.set() docs for all the details and special properties available for a set().

You can chain these calls together and use other convenience methods like to(), call(), from(), etc. to build out sequences very quickly:

//create a timeline that calls myFunction() when it completes
var tl = gsap.timeline({ onComplete: myFunction });

//now we'll use chaining, but break each step onto a different line for readability...

//tween element's x from -100
tl.from(element, { duration: 1, x: -100 })

  //then tween element's y to 50
  .to(element, { duration: 1, y: 50 })

  //then set element's opacity to 0.5 immediately
  .set(element, { opacity: 0 })

  //then call otherFunction()
  .call(otherFunction)

  //finally tween the rotation of all elements with the class "myClass" to 45 and stagger the start times by 0.25 seconds
  .to(".myClass", { duration: 1.5, rotation: 45, stagger: 0.25 });

Positioning a set() in a timeline​

By default, set() calls are added to the end of the timeline but you can use the position parameter to control precisely where things are placed. It uses a flexible syntax with the following options:

  • Absolute time (in seconds) measured from the start of the timeline, as a number like 3

    // insert exactly 3 seconds from the start of the timeline
    tl.set(".class", { x: 100 }, 3);

  • Label, like "someLabel". If the label doesn't exist, it'll be added to the end of the timeline.

    // insert at the "someLabel" label
    tl.set(".class", { x: 100 }, "someLabel");

  • "<" The start of previous animation**. Think of < as a pointer back to the start of the previous animation.

    // insert at the START of the  previous animation
    tl.set(".class", { x: 100 }, "<");

  • ">" - The end of the previous animation**. Think of > as a pointer to the end of the previous animation.

    // insert at the END of the previous animation
    tl.set(".class", { x: 100 }, ">");

  • A complex string where "+=" and "-=" prefixes indicate relative values. When a number follows "<" or ">", it is interpreted as relative so "<2" is the same as "<+=2". Examples:

    • "+=1" - 1 second past the end of the timeline (creates a gap)
    • "-=1" - 1 second before the end of the timeline (overlaps)
    • "myLabel+=2" - 2 seconds past the label "myLabel"
    • "<+=3" - 3 seconds past the start of the previous animation
    • "<3" - same as "<+=3" (see above) ("+=" is implied when following "<" or ">")
    • ">-0.5" - 0.5 seconds before the end of the previous animation. It's like saying "the end of the previous animation plus -0.5"

  • A complex string based on a percentage. When immediately following a "+=" or "-=" prefix, the percentage is based on total duration of the animation being inserted. When immediately following "<" or ">", it's based on the total duration of the previous animation. Note: total duration includes repeats/yoyos. Examples:

    • "-=25%" - overlap with the end of the timeline by 25% of the inserting animation's total duration
    • "+=50%" - beyond the end of the timeline by 50% of the inserting animation's total duration, creating a gap
    • "<25%" - 25% into the previous animation (from its start). Same as ">-75%" which is negative 75% from the end of the previous animation.
    • "<+=25%" - 25% of the inserting animation's total duration past the start of the previous animation. Different than "<25%" whose percentage is based on the previous animation's total duration whereas anything immediately following "+=" or "-=" is based on the inserting animation's total duration.
    • "myLabel+=30%" - 30% of the inserting animation's total duration past the label "myLabel".

*Percentage-based values were added in GSAP 3.7.0
**The "previous animation" refers to the most recently-inserted animation, not necessarily the animation that is closest to the end of the timeline.

Position Parameter Interactive Demo​

tl.to(".green", { x: 0, duration: 1 }, 1);
Reference point
Offset

Seconds from the reference point.

Be sure to read the Position Parameter article which includes interactive timeline visualizations and a video.

The default immediateRender value is false. For more information about immediateRender, see this article.

Contents