You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/reference/react/ViewTransition.md
+19-19Lines changed: 19 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -29,9 +29,9 @@ import {ViewTransition} from 'react';
29
29
30
30
---
31
31
32
-
## Reference {/*reference*/}
32
+
## Reference {/*reference*/}
33
33
34
-
### `<ViewTransition>` {/*viewtransition*/}
34
+
### `<ViewTransition>` {/*viewtransition*/}
35
35
36
36
Wrap elements in `<ViewTransition>` to animate them when they update inside a [Transition](/reference/react/useTransition). React uses the following heuristics to determine if a View Transition activates for an animation:
37
37
@@ -44,7 +44,7 @@ By default, `<ViewTransition>` animates with a smooth cross-fade (the browser de
44
44
45
45
<DeepDive>
46
46
47
-
#### How does `<ViewTransition>` work? {/*how-does-viewtransition-work*/}
47
+
#### How does `<ViewTransition>` work? {/*how-does-viewtransition-work*/}
48
48
49
49
Under the hood, React applies `view-transition-name` to inline styles of the nearest DOM node nested inside the `<ViewTransition>` component. If there are multiple sibling DOM nodes like `<ViewTransition><div /><div /></ViewTransition>` then React adds a suffix to the name to make each unique but conceptually they're part of the same one. React doesn't apply these eagerly but only at the time that boundary should participate in an animation.
50
50
@@ -70,7 +70,7 @@ After the finished Promise of the `startViewTransition` is resolved, React will
70
70
71
71
</DeepDive>
72
72
73
-
#### Props {/*props*/}
73
+
#### Props {/*props*/}
74
74
75
75
By default, `<ViewTransition>` animates with a smooth cross-fade. You can customize the animation, or specify a shared element transition, with these props:
76
76
@@ -81,7 +81,7 @@ By default, `<ViewTransition>` animates with a smooth cross-fade. You can custom
81
81
-**optional**`default`: A string or object. The [View Transition Class](#view-transition-class) used when no other matching activation prop is found.
82
82
-**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.
83
83
84
-
#### Callback {/*events*/}
84
+
#### Callback {/*events*/}
85
85
86
86
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 `<ViewTransition>` per Transition.
87
87
@@ -114,7 +114,7 @@ Each callback can optionally return a **cleanup function**. The cleanup function
114
114
</ViewTransition>
115
115
```
116
116
117
-
### View Transition Class {/*view-transition-class*/}
117
+
### View Transition Class {/*view-transition-class*/}
118
118
119
119
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.
120
120
@@ -123,7 +123,7 @@ The View Transition Class is the CSS class name(s) applied by React during the t
123
123
124
124
The value `'none'` can be used to prevent a View Transition from activating for a specific trigger.
@@ -152,7 +152,7 @@ When the `<ViewTransition>` activates an "enter" animation, React will add the c
152
152
153
153
In the future, CSS libraries may add built-in animations using View Transition Classes to make this easier to use.
154
154
155
-
#### Caveats {/*caveats*/}
155
+
#### Caveats {/*caveats*/}
156
156
157
157
- By default, `setState` updates immediately and does not activate `<ViewTransition>`, only updates wrapped in a [Transition](/reference/react/useTransition). You can also use [`<Suspense>`](/reference/react/Suspense) to opt-in to a Transition to [reveal content](/reference/react/Suspense#revealing-content-together-at-once).
158
158
-`<ViewTransition>` creates an image that can be moved around, scaled and cross-faded. Unlike Layout Animations you may have seen in React Native or Motion, this means that not every individual Element inside of it animates its position. This can lead to better performance and a more continuous feeling, smooth animation compared to animating every individual piece. However, it can also lose continuity in things that should be moving by themselves. So you might have to add more `<ViewTransition>` boundaries manually as a result.
@@ -161,9 +161,9 @@ In the future, CSS libraries may add built-in animations using View Transition C
161
161
162
162
---
163
163
164
-
## Usage {/*usage*/}
164
+
## Usage {/*usage*/}
165
165
166
-
### Animating an element on enter/exit {/*animating-an-element-on-enter*/}
166
+
### Animating an element on enter/exit {/*animating-an-element-on-enter*/}
167
167
168
168
Enter/Exit Transitions trigger when a `<ViewTransition>` is added or removed by a component in a transition:
169
169
@@ -368,7 +368,7 @@ function Component() {
368
368
369
369
---
370
370
371
-
### Animating a shared element {/*animating-a-shared-element*/}
371
+
### Animating a shared element {/*animating-a-shared-element*/}
372
372
373
373
Normally, we don't recommend assigning a name to a `<ViewTransition>` and instead let React assign it an automatic name. The reason you might want to assign a name is to animate between completely different components when one tree unmounts and another tree mounts at the same time. To preserve continuity.
374
374
@@ -613,7 +613,7 @@ import {MY_NAME} from './shared-name';
613
613
614
614
---
615
615
616
-
### Animating reorder of items in a list {/*animating-reorder-of-items-in-a-list*/}
616
+
### Animating reorder of items in a list {/*animating-reorder-of-items-in-a-list*/}
@@ -1041,7 +1041,7 @@ It's important to properly use keys to preserve identity when reordering lists.
1041
1041
1042
1042
---
1043
1043
1044
-
### Animating from Suspense content {/*animating-from-suspense-content*/}
1044
+
### Animating from Suspense content {/*animating-from-suspense-content*/}
1045
1045
1046
1046
Just like any Transition, React waits for data and new CSS (`<link rel="stylesheet" precedence="...">`) before running the animation. In addition to this, ViewTransitions also wait up to 500ms for new fonts to load before starting the animation to avoid them flickering in later. For the same reason, an image wrapped in ViewTransition will wait for the image to load.
1047
1047
@@ -1299,7 +1299,7 @@ You can achieve different effects depending on where you choose to place the `<V
1299
1299
1300
1300
---
1301
1301
1302
-
### Opting-out of an animation {/*opting-out-of-an-animation*/}
1302
+
### Opting-out of an animation {/*opting-out-of-an-animation*/}
1303
1303
1304
1304
Sometimes you're wrapping a large existing component, like a whole page, and you want to animate some updates, such as changing the theme. However, you don't want it to opt-in all updates inside the whole page to cross-fade when they're updating. Especially if you're incrementally adding more animations.
1305
1305
@@ -1317,7 +1317,7 @@ This will only animate if the theme changes and not if only the children update.
By default, `<ViewTransition>` includes the default cross-fade from the browser.
1323
1323
@@ -1762,7 +1762,7 @@ button:hover {
1762
1762
1763
1763
</Sandpack>
1764
1764
1765
-
### Customizing animations with types {/*customizing-animations-with-types*/}
1765
+
### Customizing animations with types {/*customizing-animations-with-types*/}
1766
1766
1767
1767
You can use the [`addTransitionType`](/reference/react/addTransitionType) API to add a class name to the child elements when a specific transition type is activated for a specific activation trigger. This allows you to customize the animation for each type of transition.
1768
1768
@@ -2091,7 +2091,7 @@ button:hover {
2091
2091
2092
2092
---
2093
2093
2094
-
### Animating imperatively with callbacks {/*animating-imperatively-with-callbacks*/}
2094
+
### Animating imperatively with callbacks {/*animating-imperatively-with-callbacks*/}
2095
2095
2096
2096
While [View Transition Classes](#view-transition-class) let you define animations with CSS, sometimes you need imperative control over the animation. The `onEnter`, `onExit`, `onUpdate`, and `onShare` callbacks give you direct access to the view transition pseudo-elements so you can animate them using the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API).
### Building View Transition enabled routers {/*building-view-transition-enabled-routers*/}
2323
+
### Building View Transition enabled routers {/*building-view-transition-enabled-routers*/}
2324
2324
2325
2325
React waits for any pending Navigation to finish to ensure that scroll restoration happens within the animation. If the Navigation is blocked on React, your router must unblock in `useLayoutEffect` since `useEffect` would lead to a deadlock.
2326
2326
2327
2327
If a `startTransition` is started from the legacy popstate event, such as during a "back"-navigation then it must finish synchronously to ensure scroll and form restoration works correctly. This is in conflict with running a View Transition animation. Therefore, React will skip animations from popstate. Therefore animations won't run for the back button. You can fix this by upgrading your router to use the Navigation API.
2328
2328
2329
2329
---
2330
2330
2331
-
## Troubleshooting {/*troubleshooting*/}
2331
+
## Troubleshooting {/*troubleshooting*/}
2332
2332
2333
2333
### My `<ViewTransition>` is not activating {/* my-viewtransition-is-not-activating */}
0 commit comments