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 }))
Debug
To debug what happends during the transition, you can add the follow CSS to highlight the parts
[data-starport-craft] {
background: #0805;
}
[data-starport-proxy]:not([data-starport-landed]) {
background: #8005;
}
