diff --git a/src/content/reference/react/ViewTransition.md b/src/content/reference/react/ViewTransition.md index 9f451eddc9d..3fc72b421e3 100644 --- a/src/content/reference/react/ViewTransition.md +++ b/src/content/reference/react/ViewTransition.md @@ -5,7 +5,7 @@ version: canary -**The `` API is currently only available in React’s Canary and Experimental channels.** +**The `` API is currently only available in React’s Canary and Experimental channels.** [Learn more about React’s release channels here.](/community/versioning-policy#all-release-channels) @@ -15,7 +15,6 @@ version: canary `` lets you animate elements that update inside a Transition. - ```js import {ViewTransition} from 'react'; @@ -41,7 +40,7 @@ Wrap elements in `` to animate them when they update inside a [T - `update`: If a `ViewTransition` has any DOM mutations inside it that React is doing (such as a prop changing) or if the `ViewTransition` boundary itself changes size or position due to an immediate sibling. If there are nested` ViewTransition` then the mutation applies to them and not the parent. - `share`: If a named `ViewTransition` is inside a deleted subtree and another named `ViewTransition` with the same name is part of an inserted subtree in the same Transition, they form a Shared Element Transition, and it animates from the deleted one to the inserted one. -By default, `` animates with a smooth cross-fade (the browser default view transition). You can customize the animation by providing a [View Transition Class](#view-transition-class) to the `` component. You can customize animations for each kind of trigger (see [Styling View Transitions](#styling-view-transitions)). +By default, `` animates with a smooth cross-fade (the browser default view transition). You can customize the animation by providing a [View Transition Class](#view-transition-class) to the `` component. You can customize animations for each kind of trigger (see [Styling View Transitions](#styling-view-transitions)). @@ -75,29 +74,50 @@ After the finished Promise of the `startViewTransition` is resolved, React will By default, `` animates with a smooth cross-fade. You can customize the animation, or specify a shared element transition, with these props: -* **optional** `enter`: A string or object. The [View Transition Class](#view-transition-class) to apply when enter is activated. -* **optional** `exit`: A string or object. The [View Transition Class](#view-transition-class) to apply when exit is activated. -* **optional** `update`: A string or object. The [View Transition Class](#view-transition-class) to apply when an update is activated. -* **optional** `share`: A string or object. The [View Transition Class](#view-transition-class) to apply when a shared element is activated. -* **optional** `default`: A string or object. The [View Transition Class](#view-transition-class) used when no other matching activation prop is found. -* **optional** `name`: A string or object. The name of the View Transition used for shared element transitions. If not provided, React will use a unique name for each View Transition to prevent unexpected animations. +- **optional** `enter`: A string or object. The [View Transition Class](#view-transition-class) to apply when enter is activated. +- **optional** `exit`: A string or object. The [View Transition Class](#view-transition-class) to apply when exit is activated. +- **optional** `update`: A string or object. The [View Transition Class](#view-transition-class) to apply when an update is activated. +- **optional** `share`: A string or object. The [View Transition Class](#view-transition-class) to apply when a shared element is activated. +- **optional** `default`: A string or object. The [View Transition Class](#view-transition-class) used when no other matching activation prop is found. +- **optional** `name`: A string or object. The name of the View Transition used for shared element transitions. If not provided, React will use a unique name for each View Transition to prevent unexpected animations. #### Callback {/*events*/} -These callbacks allow you to adjust the animation imperatively using the [animate](https://developer.mozilla.org/en-US/docs/Web/API/Element/animate) APIs: +These callbacks allow you to control the animation imperatively using the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API). React calls them after the View Transition's [`ready`](https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition/ready) Promise resolves, once built-in default animations have already been computed. Only one callback fires per `` per Transition. + +- **optional** `onEnter`: `(instance, types) => void | (() => void)`. Called when this `` is inserted during a Transition without a matching named pair. Use this to animate the entering element imperatively. +- **optional** `onExit`: `(instance, types) => void | (() => void)`. Called when this `` is removed during a Transition without a matching named pair. Use this to animate the exiting element imperatively. +- **optional** `onShare`: `(instance, types) => void | (() => void)`. Called when this `` is part of a shared element Transition—where a named `` is deleted and another with the same name is inserted. Takes precedence over `onEnter` and `onExit`. Use this to animate the shared element Transition imperatively. +- **optional** `onUpdate`: `(instance, types) => void | (() => void)`. Called when this `` has DOM mutations inside it, or when the boundary itself changes size or position due to a sibling change. Use this to animate content updates imperatively. + +Each callback receives two arguments: -* **optional** `onEnter`: A function. React calls `onEnter` after an "enter" animation. -* **optional** `onExit`: A function. React calls `onExit` after an "exit" animation. -* **optional** `onShare`: A function. React calls `onShare` after a "share" animation. -* **optional** `onUpdate`: A function. React calls `onUpdate` after an "update" animation. +- `instance`: A View Transition instance object that provides access to the view transition [pseudo-elements](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API/Using#the_view_transition_process). Call `instance.old.animate(keyframes, options)` and `instance.new.animate(keyframes, options)` to imperatively control the animation. The instance has these properties: + - `name`: The `view-transition-name` string for this boundary. + - `group`: The `::view-transition-group` pseudo-element. Supports `.animate()`, `.getAnimations()`, and `.getComputedStyle()`. + - `imagePair`: The `::view-transition-image-pair` pseudo-element. Supports `.animate()`, `.getAnimations()`, and `.getComputedStyle()`. + - `old`: The `::view-transition-old` pseudo-element (the snapshot of the previous state). Supports `.animate()`, `.getAnimations()`, and `.getComputedStyle()`. + - `new`: The `::view-transition-new` pseudo-element (the live representation of the new state). Supports `.animate()`, `.getAnimations()`, and `.getComputedStyle()`. +- `types`: An `Array` of [Transition Types](/reference/react/addTransitionType) included in the animation. Empty array if no types were specified. -Each callback receives as arguments: -- `element`: The DOM element that was animated. -- `types`: The [Transition Types](/reference/react/addTransitionType) included in the animation. +Each callback can optionally return a **cleanup function**. The cleanup function is called when the View Transition finishes, allowing you to cancel any manually started animations: + +```js + { + const anim = instance.new.animate([{opacity: 0}, {opacity: 1}], { + duration: 500, + }); + return () => anim.cancel(); + }}> +
...
+
+``` ### View Transition Class {/*view-transition-class*/} The View Transition Class is the CSS class name(s) applied by React during the transition when the ViewTransition activates. It can be a string or an object. + - `string`: the `class` added on the child elements when activated. If `'none'` is provided, no class will be added. - `object`: the class added on the child elements will be the key matching View Transition type added with `addTransitionType`. The object can also specify a `default` to use if no matching type is found. @@ -115,7 +135,6 @@ To customize the animation for a `` you can provide a View Trans For example, to customize an "enter" animation, provide a class name to the `enter` prop: - ```js ``` @@ -124,15 +143,13 @@ When the `` activates an "enter" animation, React will add the c ```css ::view-transition-group(.slide-in) { - } ::view-transition-old(.slide-in) { - } ::view-transition-new(.slide-in) { - } ``` + In the future, CSS libraries may add built-in animations using View Transition Classes to make this easier to use. #### Caveats {/*caveats*/} @@ -144,7 +161,6 @@ In the future, CSS libraries may add built-in animations using View Transition C --- - ## Usage {/*usage*/} ### Animating an element on enter/exit {/*animating-an-element-on-enter*/} @@ -169,14 +185,14 @@ function Parent() { } ``` -When `setShow` is called, `show` switches to `true` and the `Child` component is rendered. When `setShow` is called inside `startTransition`, and `Child` renders a `ViewTransition` before any other DOM nodes, an `enter` animation is triggered. +When `setShow` is called, `show` switches to `true` and the `Child` component is rendered. When `setShow` is called inside `startTransition`, and `Child` renders a `ViewTransition` before any other DOM nodes, an `enter` animation is triggered. When `show` switches back to `false`, an `exit` animation is triggered. ```js src/Video.js hidden -function Thumbnail({ video, children }) { +function Thumbnail({video, children}) { return (