Skip to content
Weblands

Transitions 🚀

Weblands supports opt-in, per-page, view transitions with just a few lines of code that enables SPA-like navigation by the new View Transitions API.

Plugin provides a <ViewTransitions /> routing component that can be added to a single page’s <head> to control page transitions as you navigate away to another page. It provides a lightweight client-side router that intercepts navigation and allows you to customize the transition between pages.

How it Works 🔍

  • Links in the viewport are detected and prefetched like in quicklink
  • When a link is clicked, the head and body are replaced using the prefetched html, then started document.startViewTransition() function call
  • Any islands in the previous page are unmounted, islands in the new page are hydrated as needed

Adding View Transitions to a Page

<template>
  <div>
    <ViewTransitions />


    <Header />
    <div>
      <slot />
    </div>
    <Footer />
  </div>
</template>


<script lang="ts">
import { defineComponent } from 'vue';
import ViewTransitions from '@belkins-group/transitions';


export default defineComponent({
  components: {
    ViewTransitions,
  },
});
</script>

Import and add the <ViewTransitions /> component to your layout component. Weblands will create default page animations based on the similarities between the old and new page, and will also provide fallback behavior for unsupported browsers.

Lifecycle events

The <ViewTransition /> router fires a number events on the document during navigation. These events provide hooks into the lifecycle of navigation, allowing you to do things like show indicators that a new page is loading, override default behavior, and restore state as navigation is completing.

The navigation process involves a preparation phase, when new content is loaded; a DOM swap phase, where the old page’s content is replaced by the new page’s content; and a completion phase where scripts are executed, loading is reported as completed and clean-up work is carried out.

Weblands View Transition API lifecycle events in order are:

  • weblands:after-swap
  • weblands:page-load
weblands:after-swap

An event that fires immediately after the new page replaces the old page. You can listen to this event on the document and trigger actions that will occur before the new page’s DOM elements render and scripts run.

This event, when listened to on the outgoing page, is useful to pass along and restore any state on the DOM that needs to transfer over to the new page.

This is the latest point in the lifecycle where it is still safe to, for example, add a dark mode class name (<html class="dark-mode">), though you may wish to do so in an earlier event.

The astro

event occurs immediately after the browser history has been updated and the scroll position has been set. Therefore, one use of targeting this event is to override the default scroll restore for history navigation. The following example resets the horizontal and vertical scroll position to the top left corner of the page for each navigation.

document.addEventListener('weblands:after-swap', () => {
  window.scrollTo({ left: 0, top: 0, behavior: 'instant' });
})
weblands:page-load

An event that fires at the end of page navigation, after the new page is visible to the user and blocking styles and scripts are loaded. You can listen to this event on the document.

The <ViewTransitions /> component fires this event both on initial page navigation for a pre-rendered page and on any subsequent navigation, either forwards or backwards.

You can use this event to run code on every page navigation, or only once ever:

document.addEventListener('weblands:page-load', () => {
 setupAnalytics();
})