---
title: "useWaapiTimeline"
description: "Run sequenced CSS tweens on the browser's native Web Animations clock."
canonical_url: "https://nanimejs.netlify.app/composables/use-waapi-timeline"
---
# useWaapiTimeline

> Run sequenced CSS tweens on the browser's native Web Animations clock.

<nuxt-link to="https://nanimejs.netlify.app/composables/composable-lifecycle#instant-play">
<badge icon="mage:zap-fill" label="Instant play" size="md" variant="soft">



</badge>
</nuxt-link>

`useWaapiTimeline` builds a timeline of CSS tweens on the browser's native
[Web Animations](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API)
clock, so the browser drives the animation and not a JavaScript loop. It is
not auto-imported, so import it from `#nanime/experimental`, or from
`nanime/experimental` in a Vue app.

<note>

It is experimental: the API can change, or the entry can be removed,
between releases.

</note>

## Build a timeline

<render-code-block-preview src="examples/composables/WaapiTimelineDemo.vue">



</render-code-block-preview>

`point(name, at)` names a time, so later tweens and callbacks can start
there.

### Place tweens with `at`

```ts
timeline
  .point('open', 2000)
  .tween(box, { translate: ['0px', '160px'], at: 400, duration: 1000 })
  .tween(box, { opacity: [0, 1], at: 'open + 150' })
```

The table shows where the last tween starts for each form of `at`, so
replace `'open + 150'` to try them. A `delay` on that tween is added to the
time.

<table>
<thead>
  <tr>
    <th align="left">
      <code>
        at
      </code>
    </th>
    
    <th align="left">
      Starts at
    </th>
    
    <th align="left">
      How
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td align="left">
      omitted
    </td>
    
    <td align="left">
      <code>
        1400
      </code>
    </td>
    
    <td align="left">
      The previous tween's end. The first tween starts at <code>
        0
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <code>
        120
      </code>
    </td>
    
    <td align="left">
      <code>
        120
      </code>
    </td>
    
    <td align="left">
      120ms from the start. Negative numbers are allowed.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <code>
        'open'
      </code>
    </td>
    
    <td align="left">
      <code>
        2000
      </code>
    </td>
    
    <td align="left">
      The time of a point registered earlier with <code>
        point()
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <code>
        '<'
      </code>
    </td>
    
    <td align="left">
      <code>
        400
      </code>
    </td>
    
    <td align="left">
      The previous tween's start.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <code>
        '< + 150'
      </code>
    </td>
    
    <td align="left">
      <code>
        550
      </code>
    </td>
    
    <td align="left">
      150ms after the previous start.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <code>
        '< + 20%'
      </code>
    </td>
    
    <td align="left">
      <code>
        600
      </code>
    </td>
    
    <td align="left">
      20% of the previous duration (200ms) after its start.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <code>
        '< + 0.2s'
      </code>
    </td>
    
    <td align="left">
      <code>
        600
      </code>
    </td>
    
    <td align="left">
      <code>
        s
      </code>
      
       and <code>
        ms
      </code>
      
       work as units.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <code>
        'open + 150'
      </code>
    </td>
    
    <td align="left">
      <code>
        2150
      </code>
    </td>
    
    <td align="left">
      150ms after <code>
        open
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

<warning>

A string that is not a point or a `<` shift, such as `'20%'` or `'120'`, is
read as a point name, so it is an error unless a point has that name. Write a
time as a number: `120`.

</warning>

### Run a function at a particular time

<render-code-block-preview src="examples/composables/WaapiTimelineCallbackDemo.vue">



</render-code-block-preview>

A callback runs `fn` when the playhead crosses `at`, going forward or
backward. `at` takes the same forms as a tween, and `callback({ fn, at })` is
the same call. Without `at` it runs at `0`. `seek()` skips the callbacks it
jumps over.

<note>

A callback after the last tween moves the timeline end to its time. It does
not count as the previous tween for `'<'`.

</note>

<warning>

A callback before `0` is an error.

</warning>

## Control playback

<render-code-block-preview src="examples/composables/WaapiTimelinePlaybackDemo.vue" :code="false">



</render-code-block-preview>

While the timeline runs or is paused, `reverse()` plays backward from the
current playhead. Before the first play or after the end, it starts from the
end. To drive a scrub bar, call `seek(value * timeline.duration)` on input,
where `value` is the bar's position from `0` to `1`.

<warning>

`progress`, `currentTime`, `paused` and `completed` are plain getters that
[do not update a template](https://nanimejs.netlify.app/composables/composable-lifecycle#properties-do-not-update-templates).
Only `isRunning` is a ref.

</warning>

## API

```ts
function useWaapiTimeline(options?: WaapiTimelineOptions): WaapiTimelineRef
```

<field-group>
<field name="options" type="WaapiTimelineOptions">

See [Options](#options).

</field>
</field-group>

### Options

<field-group>
<field name="defaults.duration" type="number">

Duration of every tween without its own `duration`. Defaults to `300`.

</field>

<field name="defaults.ease" type="WaapiTimelineEase">

Easing of every tween without its own `ease`. Accepts the same values as
[`ease`](#easing). Defaults to `'linear'`.

</field>

<field name="autoplay" type="boolean">

Plays when the component mounts. Outside `setup()` it plays after the
current synchronous code, so register the tweens right after creating the
timeline. Defaults to `false`.

<note>

With no tweens registered when it runs, it logs a warning and does not
play.

</note>
</field>

<field name="fill" type="'auto' | 'none' | 'forwards' | 'both'">

`'auto'` gives the first tween on each property of an element
`fill: 'both'` and every later one `fill: 'forwards'`. Any other value
applies to every tween as-is. Defaults to `'auto'`.

<note>

With `'auto'`, a later tween on the same property does not apply its `from`
before it starts, so each end value holds until the next tween begins. With
`'both'` it does, so the first tween in a sequence on one property is never
seen. With `'none'`, the element shows its own CSS outside each tween.

</note>
</field>

<field name="isReducedMotion" type="() => boolean">

When it returns `true`, playback jumps to the end it moves toward: the last
frame going forward, the first going backward. Callbacks run once in
playback order. Defaults to the module's
[`reducedMotion`](https://nanimejs.netlify.app/guides/accessibility) setting.

</field>

<field name="onRunningChange" type="(running: boolean) => void">

Called with `true` when the timeline starts running, and with `false` each
time its status changes to paused, finished or idle.

</field>
</field-group>

### Tween parameters

```ts
timeline.tween(panel, {
  opacity: [0, 1, 0.6],
  transform: { from: 'translateY(12px)', to: 'translateY(0)' },
  duration: 400,
  ease: 'ease-out',
  at: 'open',
})
```

The target is an element, an array of elements, a CSS selector, a component
instance, or a template ref or getter that returns one. Every key other than
`at`, `duration`, `delay` and `ease` is a CSS property. Its value takes one
of these forms:

<table>
<thead>
  <tr>
    <th align="left">
      Value
    </th>
    
    <th align="left">
      Example
    </th>
    
    <th align="left">
      Animates
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td align="left">
      One value
    </td>
    
    <td align="left">
      <code>
        opacity: 1
      </code>
    </td>
    
    <td align="left">
      From the element's current value to it.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <code>
        [from, to]
      </code>
    </td>
    
    <td align="left">
      <code>
        opacity: [0, 1]
      </code>
    </td>
    
    <td align="left">
      From the first value to the second.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      <code>
        { from, to }
      </code>
    </td>
    
    <td align="left">
      <code>
        opacity: { from: 0 }
      </code>
    </td>
    
    <td align="left">
      Either key can be left out, and the element's current value fills the gap.
    </td>
  </tr>
  
  <tr>
    <td align="left">
      Three or more stops
    </td>
    
    <td align="left">
      <code>
        opacity: [0, 1, 0.6]
      </code>
    </td>
    
    <td align="left">
      Through each stop in turn, evenly spaced.
    </td>
  </tr>
</tbody>
</table>

The values in a pair or in stops are all numbers or all strings. When stops
need different timing or easing, use one tween per stop.

<note>

The tween's `ease` shapes the progress of the whole tween, not each segment
between stops. Keyframe offsets and per-keyframe easing are not supported.

</note>

A tween with a `from` starts there, not where an earlier tween on the same
property left off. Give each later tween the previous one's `to` as its
`from`:

```ts
timeline
  .tween(box, { translate: ['0px', '80px'] })
  // wrong: translate: ['0px', '160px'] jumps the box back to 0px
  .tween(box, { translate: ['80px', '160px'] })
```

<field-group>
<field name="at" type="number | string">

When the tween starts. See [Place tweens with `at`](#place-tweens-with-at)
for every form. Defaults to the end of the previous tween, or `0` for the
first tween.

</field>

<field name="duration" type="number">

Defaults to `defaults.duration`.

</field>

<field name="delay" type="number">

Added to the start from `at`. Defaults to `0`.

</field>

<field name="ease" type="WaapiTimelineEase">

See [Easing](#easing). Defaults to `defaults.ease`.

</field>
</field-group>

<warning>

Values go to the Web Animations API as-is. CSS properties such as
`translate`, `rotate` and `scale` work, but lengths need units, and
AnimeJS-only names such as `x` and `y` do nothing, with no error. A
`stagger()` value as a CSS property is an error, and as `delay` or `duration` it
becomes `0`. Use [`useWaapiAnimate`](https://nanimejs.netlify.app/composables/use-waapi-animate) for `x`,
`y` and `stagger()`.

</warning>

### Easing

`ease` takes a CSS easing string (`'ease-out'`, `'cubic-bezier(...)'`,
`'steps(...)'`, `'linear(...)'`). Pass `{ forward, reverse }` to use another
curve while the timeline plays backward:

```ts
timeline.tween(panel, {
  opacity: [0, 1],
  ease: { forward: 'ease-out', reverse: 'ease-in' },
})
```

`reverse` defaults to `forward`. When you call `reverse()` or `play()` while
the timeline is running or paused, a tween already in progress keeps its
current value and runs the rest of its course on the other curve.

<note>

After a direction change, a tween can end slightly before or after the
timeline does. With overshooting curves such as `back` or `elastic`, a tween
can also jump slightly at the direction change. Callbacks still run at their
set times.

</note>

To use an AnimeJS easing, convert it to a CSS string with `waapi.convertEase()`:

```ts
import { waapi } from 'animejs/waapi'
import { eases } from 'animejs/easings'

timeline.tween(panel, {
  opacity: [0, 1],
  ease: waapi.convertEase(eases.outBack(3)),
})
```

<warning>

An easing that is not a CSS easing string logs a warning once and falls back
to `'linear'`.

</warning>

### Returns

Returns a `WaapiTimelineRef`: a plain object whose methods do
not depend on `this`, so destructuring works. Every method returns the same
timeline, so calls chain. Open the Types block at the end of this section for
each member and what it does.

You can call `play()` or `seek()` in `setup()`. The call waits for the
component to mount, so the timeline builds once template refs point at
elements.

<warning>

`tween()`, `point()` and `callback()` are errors after the first call to
`play()`, `reverse()`, `restart()`, `alternate()` or `seek()`.

</warning>

<note>

An error throws in development. In production it is logged with
`console.error` and the call is skipped.

</note>

### createWaapiTimeline

`createWaapiTimeline()` is the same timeline without mount and unmount
handling. `isRunning` is a plain boolean, you call `cancel()` when you are
done, and the module's `reducedMotion` setting is ignored unless you pass
`isReducedMotion`:

```ts
const timeline = createWaapiTimeline()
timeline.tween('.panel', { opacity: [0, 1] })
timeline.play()
```

Its targets are DOM elements, arrays, selectors, node lists, or a function
that returns one.

<collapsible name="Types">

```ts
interface WaapiTimelineRef {
  // add steps; all three are errors after the first playback call
  tween: (target: WaapiTimelineRefTarget, params: WaapiTweenParams) => WaapiTimelineRef
  // (fn, at) or ({ fn, at }); at defaults to 0, a callback after the last tween moves the timeline end to its time
  callback: (input: WaapiTimelineCallbackInput, at?: WaapiTimelinePosition) => WaapiTimelineRef
  // register a point before the tweens that use it
  point: (name: string, at: WaapiTimelinePosition) => WaapiTimelineRef

  // from a pause: continue; running the other way: turn around; finished: replay from 0
  play: () => WaapiTimelineRef
  // play() in the other direction; finished: replay from the end
  reverse: () => WaapiTimelineRef
  // does nothing unless running
  pause: () => WaapiTimelineRef
  // continue a paused timeline in its direction
  resume: () => WaapiTimelineRef
  // seek to 0 and play forward
  restart: () => WaapiTimelineRef
  // play the other way; a timeline that has not played yet plays forward
  alternate: () => WaapiTimelineRef
  // ms, clamped; keeps running unless it lands on an end; skips callbacks
  seek: (time: number) => WaapiTimelineRef
  // remove the animations so elements show their own CSS; next play rebuilds
  cancel: () => WaapiTimelineRef

  // true while playing in either direction
  readonly isRunning: Readonly<Ref<boolean>>
  // ms, known before the first build
  readonly duration: number
  // ms, 0 before the first build
  readonly currentTime: number
  // currentTime / duration, 0 to 1
  readonly progress: number
  // after pause(), or a seek() that stops before the end
  readonly paused: boolean
  // reached an end and stopped
  readonly completed: boolean
}

type WaapiTimelineElement
  = | HTMLElement
    | SVGElement
    | HTMLElement[]
    | SVGElement[]
    | ComponentPublicInstance

type WaapiTimelineRefTarget
  = | WaapiTimelineElement
    | string
    | null
    | undefined
    | MaybeRefOrGetter<WaapiTimelineElement | string | null | undefined>

interface WaapiTimelineCallback {
  fn: () => void
  at?: WaapiTimelinePosition
}

type WaapiTimelineCallbackInput = (() => void) | WaapiTimelineCallback

type WaapiTimelinePosition = number | string
type WaapiTimelineValue = string | number
type WaapiTimelinePair = readonly [string, string] | readonly [number, number]

interface WaapiTimelineRange {
  from?: WaapiTimelineValue
  to?: WaapiTimelineValue
}

type WaapiTimelineStops = readonly string[] | readonly number[]

type WaapiTimelineFrame = WaapiTimelineValue | WaapiTimelinePair | WaapiTimelineStops | WaapiTimelineRange

type WaapiTimelineFill = 'auto' | 'none' | 'forwards' | 'both'

interface WaapiTimelineEasePair {
  forward: string
  reverse?: string
}

type WaapiTimelineEase = string | WaapiTimelineEasePair

interface WaapiTimelineDefaults {
  duration?: number
  ease?: WaapiTimelineEase
}

interface WaapiTimelineOptions {
  defaults?: WaapiTimelineDefaults
  autoplay?: boolean
  fill?: WaapiTimelineFill
  isReducedMotion?: () => boolean
  onRunningChange?: (running: boolean) => void
}

type WaapiTweenParams = {
  at?: WaapiTimelinePosition
  duration?: number
  delay?: number
  ease?: WaapiTimelineEase
} & Record<string, WaapiTimelineFrame | WaapiTimelinePosition | WaapiTimelineEase | undefined>
```

</collapsible>

## Avoid common mistakes

### Don't use `<` for the previous end

```ts
timeline
  .tween(first, { opacity: [0, 1] })
  // wrong: at: '<' starts with first, not after it
  .tween(second, { opacity: [0, 1] })
```

With `at: '<'`, the second tween runs together with the first and no error
is raised. In AnimeJS `<` is the previous tween's end and `<<` is its start.
Here `<` is the start and `<<` is an error. Leave `at` out to start after the
previous tween. In AnimeJS an omitted position appends to the end of the
whole timeline, and here it follows the previous tween you registered.

### Fix a tween that never runs

```ts
const panel = useTemplateRef('panel') // inside v-if="open"

timeline.tween(panel, { opacity: [0, 1] })

watch(panel, (element) => {
  // wrong: timeline.play()
  if (element) timeline.cancel().play()
})
```

The timeline looks up its targets once, at the first playback call. A target
that is `null` then is skipped with no error. Each time the `v-if` opens, Vue
also renders a new element that the old build never saw. Watch the template
ref, and call `cancel()` before `play()` so the timeline looks the ref up
again.

## See also

- [`useAnimeTimeline`](https://nanimejs.netlify.app/composables/use-anime-timeline): the stable
AnimeJS timeline with labels, stagger, `sync`, seek and callbacks
- [`useWaapiAnimate`](https://nanimejs.netlify.app/composables/use-waapi-animate): one WAAPI animation
with AnimeJS value normalization
- [Composable lifecycle](https://nanimejs.netlify.app/composables/composable-lifecycle)


## Sitemap

See the full [sitemap](https://nanimejs.netlify.app/sitemap.md) for all pages.
