---
url: /reference/items/Motion/js-api.md
---
# JS API
Animate the component's root element with [Motion](https://motion.dev).
## Options
Object options are parsed as JSON: quote the keys (`data-option-animate='{ "x": 100 }'`). The available keyframes and transition settings are Motion's own — see the [`animate()` documentation](https://motion.dev/docs/animate) for the full vocabulary.
### `initial`
* Type: `DOMKeyframesDefinition`
* Default: `{}`
Styles applied to the element on mount, before anything plays. Use it to define the starting state of an enter animation without a flash of the final state. It doubles as the starting point of the [`animate`](#animate) keyframes, so the declared animation always plays from here — however many times it runs.
```html {3}
…
```
### `animate`
* Type: `DOMKeyframesDefinition`
* Default: `{}`
The target keyframes of the animation. They play on mount when [`autoplay`](#autoplay) is enabled.
Each property the [`initial`](#initial) option also describes starts from that style, so the declared animation replays identically for as long as the options stand — declare the starting state once, in `initial`:
```html {3,4}
…
```
A property `initial` says nothing about animates from whatever the element currently shows, which is what a one-off transition to a new state wants. To pin a starting point without painting it on mount, write that property as a `[from, to]` array (`{ "opacity": [0.2, 1] }`) — an explicit array is never overridden.
### `transition`
* Type: `AnimationOptions`
* Default: `{}`
Motion's animation options: `duration`, `delay`, `ease`, `type` (`"tween"`, `"spring"`, `"inertia"`), `repeat`, spring physics, etc.
```html {4}
…
```
### `autoplay`
* Type: `boolean`
* Default: `false`
Whether the `animate` keyframes play automatically on mount. Enable it with the `data-option-autoplay` attribute; without it, playback waits for an explicit `play()`.
```html {4}
…
```
### `hover`
* Type: `DOMKeyframesDefinition`
* Default: `{}`
Keyframes applied while the element is hovered, through Motion's [`hover()`](https://motion.dev/docs/hover) — real hover only, touch emulation is filtered out. When the hover ends, a new animation plays **forward** to the base values of the properties the gesture touched, with the same [`transition`](#transition) — the same return Motion for React performs when it deactivates a `whileHover` variant. The base value of each property is read from the element once, the first time a gesture touches it, so the return never plays the easing or spring curve backward and never depends on a gesture animation still being around.
```html {3}
…
```
### `press`
* Type: `DOMKeyframesDefinition`
* Default: `{}`
Keyframes applied while the element is pressed, through Motion's [`press()`](https://motion.dev/docs/press) — pointer and keyboard alike, so the state is accessible for free. Returns to the base values like `hover` when the press ends.
### `inView`
* Type: `DOMKeyframesDefinition`
* Default: `{}`
Keyframes applied when the element enters the viewport, through Motion's [`inView()`](https://motion.dev/docs/inview). Returns to the base values when the element leaves, unless [`once`](#once) is set. Declaring [`initial`](#initial) is the way to choose those base values: it is applied on mount, so it is what the element holds when the first reveal reads it.
```html {3,4}
…
```
### `inViewMargin`
* Type: `string`
* Default: `''`
The viewport margin for the `inView` detection, in CSS margin syntax (e.g. `"-100px"` to trigger 100px inside the viewport).
### `inViewAmount`
* Type: `'some' | 'all' | number`
* Default: `'some'`
How much of the element must be visible to trigger `inView`: `"some"`, `"all"`, or a `0`–`1` proportion.
### `once`
* Type: `boolean`
* Default: `false`
When set, the `inView` keyframes play once and the reached styles persist — the element is no longer watched.
::: info Gesture animations are transient
The gesture options animate alongside the declared animation: they never become the [current animation](#methods) and emit no lifecycle events — and neither does the animation returning to the base values. Like `scroll()`, the gesture functions are not part of `motion/mini` — a gesture option warns and is skipped when the [provided module](#providing-the-motion-dependency) lacks its function.
:::
## Events
All events are dispatched as bubbling `CustomEvent`s on the component's element, so they can be listened to with [`Action`](/reference/items/Action/)'s `data-on:` attribute — either on the same element or on an ancestor. Use the `.stop` modifier to contain them.
| Event | Fired when |
| ----------------- | -------------------------------------------------------------------------- |
| `motion-play` | a playback starts (`autoplay`, `play()`, `reverse()` or `animate()`). |
| `motion-pause` | the current animation is paused. |
| `motion-complete` | the current animation finishes. |
| `motion-stop` | the current animation is stopped, keeping the styles it reached. |
| `motion-cancel` | the current animation is cancelled, reverting to the pre-animation styles. |
```html {4}
…
```
## Methods
The component holds a single current animation. `play()` and `reverse()` always drive the animation declared by the options — recreating it when an imperative `animate()` call superseded it — while `pause()`, `seek()`, `stop()`, `cancel()` and `complete()` act on whichever animation is current. `play()`, `reverse()` and `animate()` return a promise that resolves when the animation settles and never rejects.
| Method | Description |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `play()` | Play the declared animation forward, creating it on first play. Restarts a finished animation. |
| `reverse()` | Play the declared animation backward. When nothing has played yet, it starts from its end. |
| `pause()` | Pause the current animation in place. |
| `seek(progress)` | Jump to a progress between `0` and `1`, creating the declared animation paused when nothing has played yet. |
| `animate(keyframes, options)` | Run a one-off animation to arbitrary keyframes; options are merged over `transition`. `play()` returns to the declared animation. |
| `stop()` | Stop the current animation and commit the styles reached. The next `play()` creates a fresh animation. |
| `cancel()` | Cancel the current animation and revert to the pre-animation styles. The next `play()` creates a fresh animation. |
| `complete()` | Jump the current animation to its end state. |
Methods are callable from an `Action` effect — on the same element or through the target syntax:
```html {2,3}
```
## Getters
| Getter | Description |
| ---------- | ---------------------------------------------------------- |
| `controls` | The current Motion playback controls, or `null` when idle. |
| `time` | The current playback time in seconds. |
| `duration` | The current animation duration in seconds. |
| `progress` | The current playback progress, from `0` to `1`. |
## Providing the Motion dependency
By default the component resolves `motion` with a lazy `import()` the first time an animation is built. To control which build is used — a specific version, the smaller `motion/mini` entry, or a module served from an import map or a CDN — inject it once with `provideMotion()` before the components mount:
```js
import { animate } from 'motion/mini';
import { provideMotion } from '@studiometa/ui-motion';
provideMotion({ animate });
```
Once provided, `@studiometa/ui-motion` never imports `motion` by specifier — it uses the instance you handed it. The injected value must satisfy the `MotionModule` type: the subset of the `motion` module the components consume. `resolveMotion()` is also exported to trigger (and await) resolution yourself, for example to preload the module.