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
+21-1
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,27 @@ Simplified `view-transition-api` for Sveltekit.
9
9
10
10
## Before we begin: what is a view transition?
11
11
12
-
I could go in thousands of details on what `view-transitions` are but what a better way of understanding them that from the words of Jake Archibald, the main mind behind them? Here's a [wonderful article](https://developer.chrome.com/docs/web-platform/view-transitions/) from him that explains what they are and how to use them in Vanilla JS.
12
+
Svelte has kinda spoiled us: we have built in animations and transitions so that we can add a little bit of micro-interactions to our websites and apps. Do you need to animate a list reordering? `flip` comes to the rescue. Is a div moving and morphing from one list to another? `crossfade` is your friend. The web platform must have seen how much svelte developers love those kind of things and has provided us with a brand new, fully progressive enhance-able api: **[the view transition API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API)**. This api not only allows you to animate between two states of your application regardless of the fact that two elements are actually the same or not (something that before was only possible with third party libraries or very complex code) but allows you to animate elements that are **on different pages**!
13
+
14
+
SvelteKit provides a way to hook into the navigation to allow the developer to start a view transition before the navigation and they do so with a very low level primitive. Here's how you can enable view transitions in SvelteKit
15
+
16
+
```ts
17
+
onNavigate((navigation) => {
18
+
if (!document.startViewTransition) return;
19
+
returnnewPromise((resolve) => {
20
+
document.startViewTransition(async () => {
21
+
resolve();
22
+
awaitnavigation.complete;
23
+
});
24
+
});
25
+
});
26
+
```
27
+
28
+
While not very complex, writing this snippets everywhere you need it can get quite tedious and sometimes based on how the `view-transition-api` works you might need to do other things like add classes or change the style of an element.
29
+
30
+
`sveltekit-view-transition` aim to ease the experience of writing easy and complex transitions in SvelteKit!
31
+
32
+
Before going in the details of how this library works and how to make use of it i want to leave here a [wonderful article](https://developer.chrome.com/docs/web-platform/view-transitions/) that explains what they are and how to use them in Vanilla JS from Jake Archibald, the main mind behind them.
@@ -199,18 +178,6 @@ function on<T extends SveltekitViewTransitionEvents>(
199
178
returnreturn_value;
200
179
}
201
180
202
-
/**
203
-
* Function to call during component initialization to add a class or a series of classes
204
-
* during the navigation. This is useful to run a different types of transition when you are going
205
-
* back to a specific page.
206
-
*
207
-
* The classes will be automatically removed at the end of the transition.
208
-
*
209
-
* @param to_add either a list of class that will always be applied or a function that returns an array
210
-
* of strings. The function will get a navigation props as input to allow you to check the to, from, route id etc.
211
-
* @param autoWrap by default the classes function is wrapped in afterNavigate so that you can
212
-
* avoid unnecessarily wrap it every time. If you need to avoid this behavior you can pass false.
213
-
*/
214
181
functionclasses(
215
182
to_add:
216
183
|string[]
@@ -249,30 +216,7 @@ function classes(
249
216
);
250
217
}
251
218
252
-
/**
253
-
* The action to specify a transition name on a specific element. You can use it on an element
254
-
* passing a string to directly assign that specific string as view transition name.
255
-
*
256
-
* If you pass an object instead you can specify a series of options:
257
-
*
258
-
* - name: required, it's the transition name that will be applied it can be either a string or a function that return a string. The function takes a navigation
259
-
* object as input. This is useful if you need to apply different transition names depending on where the navigation is going.
260
-
* - classes: either an array of strings or a function that returns an array of string that will be applied
261
-
* during the transition. The function will take a navigation object
262
-
* - applyImmediately: by default when you specify a transition name it will only be applied when it's actually navigating
263
-
* following the suggestion from Jake Archibald himself (the creator of the view transition api) https://twitter.com/jaffathecake/status/1697541871847748098?s=20
264
-
* that you should not add transition names to everything but only to the elements involved in the transition. Sometimes tho you want to
265
-
* 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).
266
-
* applyImmediately is either a boolean or a function that take the navigation object (please note that this is the navigation object) from
267
-
* 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.
268
-
* - shouldApply: as mentioned above this can be either a boolean or a function that takes a navigation object (this time the `from` is
269
-
* 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.
270
-
* This is useful when you want to navigate from a list to a detail.
271
-
*
272
-
* @param node The element to apply the action to
273
-
* @param props either a string for a simple view transition name or a set of options
@@ -434,9 +378,65 @@ export function setupViewTransition() {
434
378
}
435
379
436
380
return{
381
+
/**
382
+
* Function used to register a callback run during the onNavigate
383
+
* @param event the event name you want to register a callback for
384
+
* @param callback The callback you want to run
385
+
* @param options The options for the add listener
386
+
* @param options.registerDuringTransition if you want to register this callback even if a transition is running (if false
387
+
* it will still be registered as soon as the transition finishes)
388
+
* @param options.avoidWrapping by default the on function is wrapped in afterNavigate so that you can
389
+
* avoid unnecessarily wrap it every time. If you need to avoid this behavior you can pass true.
390
+
* @param options.autoClean wether the listener clean automatically after has been applied or it requires manual cleaning.
391
+
* it defaults to true
392
+
* @returns A function to deregister the callback
393
+
*/
437
394
on,
395
+
/**
396
+
* This function is used to deregister from an event. A function that
397
+
* deregister from an event is also returned from the on function.
398
+
* @param event the event name you want to deregister from
399
+
* @param callback the callback reference you want to deregister
400
+
* @param autoWrap by default the off function is wrapped in afterNavigate so that you can
401
+
* avoid unnecessarily wrap it every time. If you need to avoid this behavior you can pass false.
402
+
*/
438
403
off,
404
+
/**
405
+
* The action to specify a transition name on a specific element. You can use it on an element
406
+
* passing a string to directly assign that specific string as view transition name.
407
+
*
408
+
* If you pass an object instead you can specify a series of options:
409
+
*
410
+
* - name: required, it's the transition name that will be applied it can be either a string or a function that return a string. The function takes a navigation
411
+
* object as input. This is useful if you need to apply different transition names depending on where the navigation is going.
412
+
* - classes: either an array of strings or a function that returns an array of string that will be applied
413
+
* during the transition. The function will take a navigation object
414
+
* - applyImmediately: by default when you specify a transition name it will only be applied when it's actually navigating
415
+
* following the suggestion from Jake Archibald himself (the creator of the view transition api) https://twitter.com/jaffathecake/status/1697541871847748098?s=20
416
+
* that you should not add transition names to everything but only to the elements involved in the transition. Sometimes tho you want to
417
+
* 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).
418
+
* applyImmediately is either a boolean or a function that take the navigation object (please note that this is the navigation object) from
419
+
* 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.
420
+
* - shouldApply: as mentioned above this can be either a boolean or a function that takes a navigation object (this time the `from` is
421
+
* 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.
422
+
* This is useful when you want to navigate from a list to a detail.
423
+
*
424
+
* @param node The element to apply the action to
425
+
* @param props either a string for a simple view transition name or a set of options
426
+
*/
439
427
transition,
428
+
/**
429
+
* Function to call during component initialization to add a class or a series of classes
430
+
* during the navigation. This is useful to run a different types of transition when you are going
431
+
* back to a specific page.
432
+
*
433
+
* The classes will be automatically removed at the end of the transition.
434
+
*
435
+
* @param to_add either a list of class that will always be applied or a function that returns an array
436
+
* of strings. The function will get a navigation props as input to allow you to check the to, from, route id etc.
437
+
* @param autoWrap by default the classes function is wrapped in afterNavigate so that you can
438
+
* avoid unnecessarily wrap it every time. If you need to avoid this behavior you can pass false.
0 commit comments