self (makes chaining easier)
Version:
GreenSock Docs
Back to GSAP
Timeline
Methods
.add()
.addLabel()
.addPause()
.call()
.clear()
.currentLabel()
.delay()
.duration()
.endTime()
.eventCallback()
.from()
.fromTo()
.getChildren()
.getTweensOf()
.invalidate()
.isActive()
.iteration()
.kill()
.nextLabel()
.pause()
.paused()
.play()
.previousLabel()
.progress()
.recent()
.remove()
.removeLabel()
.removePause()
.repeat()
.repeatDelay()
.restart()
.resume()
.reverse()
.reversed()
.seek()
.set()
.shiftChildren()
.startTime()
.then()
.time()
.timeScale()
.to()
.totalDuration()
.totalProgress()
.totalTime()
.tweenFromTo()
.tweenTo()
.yoyo()
Timeline
.add()
.add( value:*, position:*, align:String, stagger:Number ) : *
[override] Adds a tween, timeline, callback, or label (or an array of them) to the timeline.
Parameters
value: *
The tween, timeline, callback, or label (or array of them) to add
position: *
(default = +=0) — Controls the placement of the object in the timeline (by default, it’s the end of the timeline, like “+=0”). Use a number to indicate an absolute time in terms of seconds, or you can use a string with a “+=” or “-=” prefix to offset the insertion point relative to the END of the timeline. For example, "+=2" would place the object 2 seconds after the end, leaving a 2-second gap. "-=2" would create a 2-second overlap. You may also use a label like "myLabel" to have the object inserted exactly at the label or combine a label and a relative offset like "myLabel+=2" to insert the object 2 seconds after “myLabel” or "myLabel-=3" to insert it 3 seconds before “myLabel”. If you define a label that doesn’t exist yet, it will automatically be added to the end of the timeline before inserting the tween there which can be quite convenient.
Be sure to read our tutorial Understanding the Position Parameter which includes interactive timeline visualizations and a video.
align: String
(default = normal) — [only relevant when the first parameter, value, is an array] Determines how the tweens/timelines/callbacks/labels in the array that is being added will be aligned in relation to each other before getting inserted. Options are: "sequence" (aligns them one-after-the-other in a sequence), "start" (aligns the start times of all of the objects (ignoring delays)), and "normal" (aligns the start times of all the tweens (honoring delays)). The default is "normal".
stagger: Number
(default = 0) — [only relevant when the first parameter, value, is an array] Staggers the inserted objects from the array that is being added by a set amount of time (in seconds). For example, if the stagger value is 0.5 and the "align" parameter is set to "start", the second one will start 0.5 seconds after the first one starts, then 0.5 seconds later the third one will start, etc. If the align property is "sequence", there would be 0.5 seconds added between each tween. Default is 0.
Returns : *
Details
Adds a tween, timeline, callback, or label (or an array of them) to the timeline.
The position parameter gives you complete control over the insertion point. By default, it’s at the end of the timeline. Use a number to indicate an absolute time in terms of seconds (or frames for frames-based timelines), or you can use a string with a “+=” or “-=” prefix to offset the insertion point relative to the END of the timeline.
For example, "+=2" would place the object 2 seconds after the end, leaving a 2-second gap. "-=2" would create a 2-second overlap. You may also use a label like "myLabel" to have the object inserted exactly at the label or combine a label and a relative offset like "myLabel+=2" to insert the object 2 seconds after “myLabel” or "myLabel-=3" to insert it 3 seconds before “myLabel”. If you define a label that doesn’t exist yet, it will automatically be added to the end of the timeline before inserting the tween which can be quite convenient.
//add a tween to the end of the timelinetl.add( gsap.to(element, {duration: 2, left: 100}) );//add a callback at 1.5 secondstl.add(func, 1.5);//add a label 2 seconds after the end of the timeline (with a gap of 2 seconds)tl.add("myLabel", "+=2");//add another timeline at "myLabel"tl.add(otherTimeline, "myLabel");//add an array of tweens 2 seconds after "myLabel"tl.add([tween1, tween2, tween3], "myLabel+=2");//add an array of tweens so that they are sequenced one-after-the-other with 0.5 seconds inbetween them, starting 2 seconds after the end of the timelinetl.add([tween1, tween2, tween3], "+=2", "sequence", 0.5);
Be sure to read our tutorial Understanding the Position Parameter which includes interactive timeline visualizations and a video.