--- url: /reference/items/MotionView/js-api.md --- # JS API Wrap DOM updates in Motion's [`animateView()`](https://motion.dev/docs/animate-view) so the change plays as a view transition. A drop-in alternative to the [`ViewTransition`](/reference/items/ViewTransition/) component — same `enter()`/`leave()`/`toggle()` methods, `state` property, events and `viewTransitionName`/`enterTo`/`leaveTo` options — but the animation is declared with Motion keyframes and transitions (including springs) instead of the `::view-transition-*` CSS pseudo-elements. ```html {2,3}
…
``` ## Options Object options are parsed as JSON: quote the keys (`data-option-new='{ "opacity": [0, 1] }'`). ### `viewTransitionName` * Type: `string` * Default: `''` Assigned as the element's [`view-transition-name`](https://developer.mozilla.org/en-US/docs/Web/CSS/view-transition-name) on mount, exactly like `ViewTransition`. Optional with `MotionView`: `animateView()` names the subjects it animates automatically. ### `enterTo` * Type: `string` * Default: `''` Classes describing the shown state. Added on `enter`, removed on `leave`. ### `leaveTo` * Type: `string` * Default: `''` Classes describing the hidden state. Added on `leave`, removed on `enter`. Usually also the element's initial class so it starts hidden. ### `transition` * Type: `ViewTransitionOptions` * Default: `{}` The root [`animateView()` options](https://motion.dev/docs/animate-view): a default transition (`duration`, `ease`, `type: "spring"`, …) for every layer of the view transition. ### `add` * Type: `string` * Default: `''` A selector resolved within the component's element: every matched element becomes an animated subject of the transition. When empty, the element itself is the subject. ### `new`, `old`, `enter`, `exit` * Type: `DOMKeyframesDefinition` * Default: `{}` Per-layer keyframes applied to each subject, mapping to the builder's [`new()`/`old()`/`enter()`/`exit()` methods](https://motion.dev/docs/animate-view): `new` and `old` animate the new and old views whether the element persists or not, while `enter` and `exit` only fire for a pure newcomer or leaver. ### `layout` * Type: `boolean` * Default: `false` Enable the layout morph on each subject (the builder's `layout()`), so position and size changes animate smoothly. ### `auto` * Type: `boolean` * Default: `true` Enable [ambient wiring](#ambient-wiring): the component wraps any DOM update announced inside its subtree and joins the lifecycle of a containing `Dialog`. Opt out with `data-option-no-auto`. ## Properties ### `state` * Type: `'entering' | 'leaving' | null` The current state of the transition: `'entering'` while entering, `'leaving'` while leaving, or `null` before any transition has run. `toggle()` reads it to decide which direction to run. ### `target` * Type: `HTMLElement` The element the `view-transition-name` and the enter and leave classes are applied to — the component's root element. ## Events The same events as [`ViewTransition`](/reference/items/ViewTransition/js-api#events), in the same order: `enter`, `enter-start`, `enter-end` around the enter transition and `leave`, `leave-start`, `leave-end` around the leave transition. ## Methods | Method | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------- | | `enter()` | Swap `leaveTo` for `enterTo` inside a view transition. Resolves once the animation settles. | | `leave()` | Swap `enterTo` for `leaveTo` inside a view transition. Resolves once the animation settles. | | `toggle()` | Toggle between enter and leave, entering first. | | `update(mutate)` | The underlying primitive: run any DOM mutation as a view transition configured by the options. Never rejects. | ## Ambient wiring Containment is the wiring: with the `auto` option (on by default), a mounted `MotionView` listens for the bubbling `js-toolkit:dom:update` event that mutating components — [`Fetch`](/reference/items/Fetch/), [`DataBind`](/reference/items/DataBind/)'s `data-bind:if` — announce before changing the DOM, and runs the announced change through `update()` so it plays as a view transition. Nesting the mutators inside the component is enough, with zero wiring attributes on either side: ```html {1}
``` A `MotionView` also joins the lifecycle of an ancestor that emits **extendable** `open` and `close` events — those built with the toolkit's [`emitExtendable()`](https://js-toolkit-v4.studiometa.dev/api/dom/emitExtendable.html), whose `detail` carries a `waitUntil()` function. [`Dialog`](/reference/items/Dialog/js-api#events) emits exactly those, so nesting a `MotionView` inside a dialog is enough: it registers `enter()` on `open` and `leave()` on `close`, and the dialog stays painted until the animation settles. It registers a **function**, not itself: `emitExtendable()` duck-types an object registration on the name of the event, and a transition component has no `open()`/`close()` to offer. See [extending the lifecycle](/reference/items/Dialog/js-api#extending-the-lifecycle-with-waituntil). Only a **containing** ancestor counts. The event is heard on the document, and the component checks that its emitter contains the root element, so a dialog elsewhere on the page animates nothing here. Opt out with `data-option-no-auto`. Explicit wiring through [`Action`](/reference/items/Action/) remains for cross-subtree topologies, where the mutator and the animated subtree are not nested: ```html {4}
``` ## Notes * The mutation is never lost: in browsers without the View Transitions API — or when the animation rejects — the update still applies, only without animation. * `animateView()` is not part of `motion/mini`: when the [provided module](/reference/items/Motion/js-api#providing-the-motion-dependency) lacks it, the component warns and applies updates directly.