⮌ back | Overview | Home

🚸 The Element Crossing

With the <ElementCrossing /> component, you can transfer selected element states across cross-document view transitions.

This component is intended to be used with CSS-only cross-document view transitions as defined in level 2 of the View Transition API. If you use Astro’s <ViewTransitions />↗ component, you do not need the <ElementCrossing /> component because you would use transition:persist↗ to persist DOM trees on navigation.

Contents

Why should I use this component?

Cross-document view transitions is all about giving multi page applications the smooth look and feel of single page applications. While users interact with the elements on a page, they change their internal state. This includes scrollbars, form input, toggle states to name a few. If the next page is loaded, those changes are lost. this might lead to rather un-smooth vie transitions. With the ElementCrossing component, you can carry over state that is important for the look and feel of your application.

How Does it Work?

The Element Crossing reads your annotations at HTML elements and transfers part of the state to the next page. The Element Crossing of the bot Bag of Tricks is the Astro version of the @vtbag/ElementCrossing. Please see the documentation there↗ for further information and demos of the effects.

Usage

Install astro-vtbot in your project as an Astro integration with npx astro add astro-vtbot or as a node package with npm install astro-vtbot.

You need to place the <ElementCrossing /> component on the pages where you want to retrieve or restore HTML element state. For cross-document transitions, the component must be present on both the old and the new page. It’s best to insert the component in your basic layout inside the <head> element.

MyLayout.astro
1
---
2
import ElementCrossing from 'astro-vtbot/components/ElementCrossing.astro';
3
---
4
<html>
5
  <head>
6
    <ElementCrossing />
7
    ...
8
  </head>
9
  ...
10
</html>

Properties

The component has a single property called experimentalFeatures. Use it like this

1
<ElementCrossing experimentalFeatures />

to switch on the experimental over-the-top flavor↗ of the Element Crossing.

Visit the documentation on how to annotate HTML elements↗ for info about configuration and real word examples.