Shared Vue component across routes with animations
Why?
It's quite common you might have a same component used in different routes (pages) with a bit different sizes and positions. Sometimes you might want to animate them when user navigates between routes to provide a smooth UX. While such animation is common to be seen in native apps, it's could be a bit challenging to do it in Web.
Vue's component structure is presented as a tree, and the child components are in different branches with their own instances. Meaning when users navigate between routes, the components are not shared across routes.
By that means you can't directly animate the changes because they are in two different instances. The good news is, there is a technique called FLIP to enumerate the transitions between them.
However, FLIP only solves the problem of transitions, the components are still not the same. During the navigation, the internal state of the component will lost.
Thus I started this new approach Starport to experiment with a better solution to fit this requirement.
How?
So since we can't share the components across different branches in the component tree, we could actually hoist them to the root so they become independent from the routes.
To allow each page to still have control of the components, we introduced a Proxy component to present the expected size and position of that component. The proxy will pass the props and position infomation to the actual component and let it "fly over" the proxy with animations.
When the transition ends and it arrived to the expected position, it will then "land down" to the actual component using the <Teleport/> component.
With this "landing" mechanism, the DOM tree will be preserved as what you will have with the original tree structure. When navigating to another route, the component then will "lift off" back to the floating state, "fly" to the new proxy's position and "land" again.
This is very similar to Terran's Buildings in StarCraft (able to leave the ground and fly to new locations). It's also the inspiration source of the project name Starport.
Install
⚗️ Experimental
npm i vue-starport
Vue Starport only works for Vue 3
Usage
At root App.vue, add <StarportCarrier> component from vue-starport at the end of the dom. <StarportCarrier> will be the place to store all the flying components.
<script setup>
import { StarportCarrier } from 'vue-starport'
</script>
<template>
<RouterView />
<StarportCarrier /> <!-- here -->
</template>
In routes, wrap the component with the <Starport> component.
<!-- PageA.vue -->
<script setup>
import { Starport } from 'vue-starport'
</script>
<template>
<div>
<!-- ... -->
<Starport port="my-id" style="height:400px">
<MyComponent :prop="value"/>
</Starport>
</div>
</template>
On the other page, we do the same thing with the same port id to identify the instance.
<!-- PageB.vue -->
<script setup>
import { Starport } from 'vue-starport'
</script>
<template>
<div>
<!-- ... -->
<Starport port="my-id" style="height:600px">
<MyComponent :prop="value"/>
</Starport>
</div>
</template>
Note that you might need to apply some styles to
<Starport>to make it have a defined size indicating the area for the "floating starcraft" to land.
Checkout the Playground for more examples.
Register Components Globally
// main.ts
import StarportPlugin from 'vue-starport'
app.use(StarportPlugin())
And then you can use Starport and StarportCarrier components without importing.
Keep Alive
By default, when navigating to a page without a corresponding <Starport> proxy to land, the component will be destroyed. If you want to keep the component alive even when it's not presented in the current route, you can set keepAlive to true for that specific instance.
<Starport keep-alive port="my-id">
<MyComponent />
</Starport>
To configure it globally, you can pass options to the plugin:
// main.ts
import StarportPlugin from 'vue-starport'
app.use(StarportPlugin({ keepAlive: true }))
Special Thanks
Thanks to @hangsman who helped to provide the initial solution of proper teleport the element and made this idea valid. Also thanks to the viewers of my live-streaming on Bilibli, those who spend time with me to working on this idea and provided useful feedback during the live.
You can check the recordings of my live-streams (in Chinese), where I wrote this project from scratch.
你可以在哔哩哔哩观看我实现此项目的 直播录像。
Sponsors
License
MIT License © 2022 Anthony Fu
75.9k Jan 9, 2023
36.2k Jan 3, 2023
6.3k Jan 6, 2023
4.5k Jan 2, 2023
4.6k Jan 3, 2023
2.9k Dec 27, 2022
2.6k Jan 5, 2023
6 Jun 20, 2021
14 Oct 7, 2022
37 Aug 14, 2022
4 Feb 19, 2022
10 Jul 1, 2022
14 Dec 24, 2022
6 Jul 24, 2022
36 Oct 20, 2022
1 Feb 23, 2022
180 Jan 3, 2023
9 Nov 19, 2022
46 Jan 2, 2023