--- url: /reference/items/GsapTimeline/js-api.md --- # JS API Compose `GsapStep` descendants into one [GSAP](https://gsap.com) timeline. ## Options Object options are JSON: quote the keys. JSON cannot contain functions or DOM nodes. The component controls the `paused`, `scrollTrigger` and `callbackScope` keys and the callbacks, and removes them with a `gsap.unsupported-vars` diagnostic. All options are responsive, and a change rebuilds the timeline once per frame. A rebuild keeps the progress and the playback state, except for a timeline that `scrollTrigger` drives. ### `timeline` * Type: `GSAP.TimelineVars` * Default: `{}` The [timeline variables](https://gsap.com/docs/v3/GSAP/Timeline/#special-properties), for example `defaults`, `delay`, `repeat` or `yoyo`. ```html {3}
…
``` ### `scrollTrigger` * Type: `boolean | ScrollTrigger.Vars` * Default: `false` Create a ScrollTrigger for the timeline. It works like the [`scrollTrigger` option of `Gsap`](/reference/items/Gsap/js-api#scrolltrigger): a bare attribute uses the root element as trigger, and the `trigger`, `endTrigger` and `pin` selectors resolve inside the root element. ### `autoplay` * Type: `boolean` * Default: `false` Play the timeline when it is built. ## `GsapStep` A `GsapStep` declares one tween of its nearest `GsapTimeline` ancestor. Its options are the [`targets`](/reference/items/Gsap/js-api#targets), [`set`](/reference/items/Gsap/js-api#set), [`from`](/reference/items/Gsap/js-api#from) and [`to`](/reference/items/Gsap/js-api#to) options of `Gsap`, plus `at`. The `targets` selector resolves inside the step, and an empty value targets the step element. A change of the options of a step rebuilds its timeline. A step without `set`, `from` and `to` reports a `gsap.empty-declaration` diagnostic and the timeline skips it. ### `at` * Type: `string` * Default: `''` The [position](https://gsap.com/resources/position-parameter/) of the step in the timeline: * a number of seconds: `"1.5"`; * a label: `"intro"`. GSAP adds the label at the end of the timeline when it does not exist yet; * a relative position: `"<"`, `">"`, `"+=0.5"`, `"-=0.2"`, `"intro+=1"`. An empty value appends the step at the end of the timeline. The `set` variables of a step go at its position, before its tween. ```html {5,9}

…

…

…
``` ## Properties | Property | Type | Description | | ----------- | ----------------------------- | -------------------------------------------------------------------- | | `animation` | `gsap.core.Animation \| null` | The current timeline, or `null` without steps and in reduced motion. | | `progress` | `number` | The progress of the current timeline, from `0` to `1`. | | `duration` | `number` | The duration of the current timeline, in seconds. | | `steps` | `GsapStep[]` | The mounted steps that the timeline owns, in DOM order. | A rebuild replaces the timeline: read `animation` when you need it, and do not keep a reference. ## Methods The timeline has the [methods of `Gsap`](/reference/items/Gsap/js-api#methods): `play()`, `pause()`, `reverse()`, `restart()`, `seek(position)`, `complete()` and `rebuild()`. `seek()` also accepts a label of the timeline. A method called before the timeline is built applies to it when it is built. ## Events The timeline dispatches the [events of `Gsap`](/reference/items/Gsap/js-api#events): `gsap-ready`, `gsap-play`, `gsap-pause`, `gsap-complete`, `gsap-reverse-complete` and `gsap-interrupt`. ## Lifecycle * The timeline waits until the DOM settles, so the steps of the markup are mounted when it builds. * A step added, removed or moved, and a change of the options of a step, rebuild the timeline once per frame. * The timeline is built in a `gsap.context()`, and a rebuild or an unmount reverts it. * When the user prefers reduced motion, the timeline does not load GSAP and builds nothing.