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: README.md
+225-4
Original file line number
Diff line number
Diff line change
@@ -60,7 +60,7 @@ The most easy and immediate setup is importing and adding `setupViewTransition`
60
60
61
61
You can target and modify the default animation with `::view-transition-old(root)` and `::view-transition-new(root)`. However it's ofter useful to have specific part of the page have different view transitions. For example the header might be fixed and we would like to animate it differently. To allow for this use case `setupViewTransition` return an object from which you can destructure `transition`.
62
62
63
-
## transition
63
+
###transition
64
64
65
65
`transition` is an action that accept a string as input and assign that string as the `view-transition-name` of that element. Plain and simple.
66
66
@@ -71,10 +71,231 @@ You can target and modify the default animation with `::view-transition-old(root
71
71
const { transition } = setupViewTransition();
72
72
</script>
73
73
74
-
<header use:transition="header" >
75
-
<!-- links -->
74
+
<header use:transition={'header'}>
75
+
<!-- links -->
76
76
</header>
77
77
<slot />
78
78
```
79
79
80
-
This will allow you to target the header with `::view-transition-old(header)` and `::view-transition-new(header)`
80
+
This will allow you to target the header with `::view-transition-old(header)` and `::view-transition-new(header)`.
81
+
82
+
Now while this may seem enough sometimes you might want to be a bit more creative with the transition names and that's why instead of a string you can also pass an object to the transition action.
83
+
84
+
#### name
85
+
86
+
This is the name of the transition, much like the string that you would've passed before it's what will end up as the `view-transition-name`. It's the only required field.
87
+
88
+
#### classes
89
+
90
+
Either an array of strings or a function that returns an array of string that will be applied during the transition. This allows you to target specific classnames in your css. For example let's say that you are clicking on a back button and when going back on an old page you want to apply a different navigation, how would you do it? Simply pass the array `["back"]` and target the classes in your css `.back::view-transition-old(yourname)` and `.back::view-transition-new(yourname)`. The function will take a `OnNavigate` object as input which is the same object that sveltekit will pass to the `onNavigate` function. It looks like this
91
+
92
+
```ts
93
+
interfaceNavigation {
94
+
/**
95
+
* Where navigation was triggered from
96
+
*/
97
+
from: {
98
+
/**
99
+
* Parameters of the target page - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object.
100
+
* Is `null` if the target is not part of the SvelteKit app (could not be resolved to a route).
101
+
*/
102
+
params:Record<string, string> |null;
103
+
/**
104
+
* Info about the target route
105
+
*/
106
+
route: { id:string|null };
107
+
/**
108
+
* The URL that is navigated to
109
+
*/
110
+
url:URL;
111
+
} |null;
112
+
/**
113
+
* Where navigation is going to/has gone to
114
+
*/
115
+
to: {
116
+
/**
117
+
* Parameters of the target page - e.g. for a route like `/blog/[slug]`, a `{ slug: string }` object.
118
+
* Is `null` if the target is not part of the SvelteKit app (could not be resolved to a route).
119
+
*/
120
+
params:Record<string, string> |null;
121
+
/**
122
+
* Info about the target route
123
+
*/
124
+
route: { id:string|null };
125
+
/**
126
+
* The URL that is navigated to
127
+
*/
128
+
url:URL;
129
+
} |null;
130
+
/**
131
+
* The type of navigation:
132
+
* - `form`: The user submitted a `<form>`
133
+
* - `leave`: The user is leaving the app by closing the tab or using the back/forward buttons to go to a different document
134
+
* - `link`: Navigation was triggered by a link click
135
+
* - `goto`: Navigation was triggered by a `goto(...)` call or a redirect
136
+
* - `popstate`: Navigation was triggered by back/forward navigation
137
+
*/
138
+
type:'form'|'leave'|'link'|'goto'|'popstate';
139
+
/**
140
+
* Whether or not the navigation will result in the page being unloaded (i.e. not a client-side navigation)
141
+
*/
142
+
willUnload:false;
143
+
/**
144
+
* In case of a history back/forward navigation, the number of steps to go back/forward
145
+
*/
146
+
delta?:number;
147
+
/**
148
+
* A promise that resolves once the navigation is complete, and rejects if the navigation
149
+
* fails or is aborted. In the case of a `willUnload` navigation, the promise will never resolve
150
+
*/
151
+
complete:Promise<void>;
152
+
}
153
+
```
154
+
155
+
as you can see it contains a lot of useful information to determine the page you are going to and conditionally apply classes based on the navigation.
156
+
157
+
An example could be this one
158
+
159
+
```svelte
160
+
<script>
161
+
import { setupViewTransition } from 'sveltekit-view-transition';
162
+
163
+
const { transition } = setupViewTransition();
164
+
</script>
165
+
166
+
<header
167
+
use:transition={{
168
+
name: 'header',
169
+
classes({ navigation }) {
170
+
if (navigation.to?.route?.id === '/') {
171
+
return ['back'];
172
+
}
173
+
},
174
+
}}
175
+
>
176
+
<a href="/">Back</a>
177
+
</header>
178
+
179
+
<!-- your component -->
180
+
```
181
+
182
+
#### applyImmediately
183
+
184
+
By default when you specify a transition name it will only be applied when it's actually navigating following [the suggestion](https://twitter.com/jaffathecake/status/1697541871847748098) from Jake Archibald himself (the creator of the view transition api) that you should not add transition names to everything but only to the elements involved in the transition. Sometimes tho you want to add a transition name immediately (for example when you are coming back from a detail page and you want to animate back an image in the list).
185
+
`applyImmediately` is either a boolean or a function that take the navigation object (please note that this is the navigation object) from the previous page so the `from` will be the page that is navigating to this page and the `to` will be this page) and returns a boolean.
186
+
187
+
Here's a simple example of this in action
188
+
189
+
```svelte
190
+
<script>
191
+
import { setupViewTransition } from 'sveltekit-view-transition';
192
+
193
+
const { transition } = setupViewTransition();
194
+
195
+
export let data;
196
+
</script>
197
+
198
+
<ul>
199
+
{#each data.posts as post (post.id)}
200
+
<li
201
+
use:transition={{
202
+
/**
203
+
* in the post/[id] page we have a matching title transition name
204
+
*/
205
+
name: 'title',
206
+
applyImmediately(navigation) {
207
+
// this will apply the title view transition to this element
208
+
// only if it's the one that matches the id we are coming from
209
+
// so for example if we were visiting /post/1 and this is the
210
+
// post with id 1. Notice that i'm checking the `from` because
211
+
// this will actually be called when the navigation is still happening
in this example when we navigate back from the `/post/1` page the title will slide in his right place in the list. Also important note: **the transition name will be added before the transition ends and removed immediately after to allow for a forward transition from another post to happen. If not removed the transition name would be duplicated**
224
+
225
+
#### shouldApply
226
+
227
+
As mentioned above this can be either a boolean or a function that takes a navigation object (this time the `from` is this page and the `to` is the page you are navigating to) and return a boolean. If the boolean is true the transition name will be applied. This is useful when you want to navigate from a list to a detail.
228
+
229
+
So completing the example above
230
+
231
+
```svelte
232
+
<script>
233
+
import { setupViewTransition } from 'sveltekit-view-transition';
234
+
235
+
const { transition } = setupViewTransition();
236
+
237
+
export let data;
238
+
</script>
239
+
240
+
<ul>
241
+
{#each data.posts as post (post.id)}
242
+
<li
243
+
use:transition={{
244
+
/**
245
+
* in the post/[id] page we have a matching title transition name. Note that
246
+
* the transition name will only be applied moments before the actual transition
247
+
* if and when the shouldApply function returns true
This function is returned from setupViewTransition and allows you to add a listener to run code in an arbitrary moment of the "lifecycle" of the view transition. It takes three arguments, the name of the event, the function and a boolean that indicates wether the callback should be added immediately (even if there's a transition running) or not. This is because there are events that runs after the component has mounted and if you add the listeners on mount specifying true as the third argument this listeners will be called immediately. This might be useful sometimes if you want to modify the state of after an incoming transition.
269
+
270
+
There are 7 types of events you can subscribe to in order of calling
271
+
272
+
- 'before-start-view-transition': event called before the transition even start if you modify the DOM here it will be included in the "screenshot" of the `view-transition`
273
+
- 'before-navigation': event called before SvelteKit start to handle the navigation the view transition has already been started
274
+
- 'before-navigation-complete': event called after SvelteKit started to handle the navigation but before it completes. The `view-transition` is still happening.
275
+
- 'after-navigation-complete': event called after the navigation from SvelteKit has completed. The `view-transition` is sill happening
276
+
- 'transition-ready': event called when the `view-transition` is ready, the pseudo-elements are created.
277
+
- 'update-callback-done': event called when the callback of the `view-transition` has finished running.
278
+
- 'transition-finished': event called when the `view-transition` finish and the new view is in place
279
+
280
+
The `on` function also returns a function that unregister the callback when called.
281
+
282
+
### off
283
+
284
+
It's a function to unsubscribe a specific handle from a specific event. You will probably rarely use this given that the `on` function already returns the unsubscribe.
285
+
286
+
### classes
287
+
288
+
Much like the `classes` function on the action this function can be called immediately in the script tag of a component to add a specific class to the `:root` element during a navigation. It can either be a array of strings or a function that returns an array of strings. The function takes as a parameter a navigation object just like the one from the action.
289
+
290
+
```svelte
291
+
<script>
292
+
import { setupViewTransition } from 'sveltekit-view-transition';
* The action to specify a transition name on a specific element. You can use it on an element
164
-
* passing a string to directly assign that specific string as view transition name.
165
-
*
166
-
* If you pass an object instead you can specify a series of options:
167
-
*
168
-
* - name: required, it's the transition name that will be applied
169
-
* - classes: either an array of strings or a function that returns an array of string that will be applied
170
-
* during the transition. The function will take a navigation object
171
-
* - applyImmediately: by default when you specify a transition name it will only be applied when it's actually navigating
172
-
* following the suggestion from Jake Archibald himself (the creator of the view transition api) https://twitter.com/jaffathecake/status/1697541871847748098?s=20
173
-
* that you should not add transition names to everything but only to the elements involved in the transition. Sometimes tho you want to
174
-
* add a transition name immediately (for example when you are coming back from a detail page and you want to animate back an image in the list).
175
-
* applyImmediately is either a boolean or a function that take the navigation object (please note that this is the navigation object) from
176
-
* the previous page so the `from` will be the page that is navigating to this page and the `to` will be this page) and returns a boolean.
177
-
* - shouldApply: as mentioned above this can be either a boolean or a function that takes a navigation object (this time the `from` is
178
-
* this page and the `to` is the page you are navigating to) and return a boolean. If the boolean is true the transition name will be applied.
179
-
* This is useful when you want to navigate from a list to a detail.
180
-
*
181
-
* @param node The element to apply the action to
182
-
* @param props either a string for a simple view transition name or a set of options
* The action to specify a transition name on a specific element. You can use it on an element
165
+
* passing a string to directly assign that specific string as view transition name.
166
+
*
167
+
* If you pass an object instead you can specify a series of options:
168
+
*
169
+
* - name: required, it's the transition name that will be applied
170
+
* - classes: either an array of strings or a function that returns an array of string that will be applied
171
+
* during the transition. The function will take a navigation object
172
+
* - applyImmediately: by default when you specify a transition name it will only be applied when it's actually navigating
173
+
* following the suggestion from Jake Archibald himself (the creator of the view transition api) https://twitter.com/jaffathecake/status/1697541871847748098?s=20
174
+
* that you should not add transition names to everything but only to the elements involved in the transition. Sometimes tho you want to
175
+
* add a transition name immediately (for example when you are coming back from a detail page and you want to animate back an image in the list).
176
+
* applyImmediately is either a boolean or a function that take the navigation object (please note that this is the navigation object) from
177
+
* the previous page so the `from` will be the page that is navigating to this page and the `to` will be this page) and returns a boolean.
178
+
* - shouldApply: as mentioned above this can be either a boolean or a function that takes a navigation object (this time the `from` is
179
+
* this page and the `to` is the page you are navigating to) and return a boolean. If the boolean is true the transition name will be applied.
180
+
* This is useful when you want to navigate from a list to a detail.
181
+
*
182
+
* @param node The element to apply the action to
183
+
* @param props either a string for a simple view transition name or a set of options
0 commit comments