Last updated: Oct 4, 2024 First published: Oct 4, 2024

The Cam-Shaft

Bump your view transition images into position to avoid that unexpected pseudo-smooth-scrolling.

The Cam-Shaft is about an issue we already resolved for Astro’s ViewTransitions (see here↗ and here↗), but it still requires support for browser-native cross-document view transitions.

What is it?

This tools is intended to avoid the pseudo-smooth-scroll effect.

See the interactive demo of the effect and the interactive demo of the solution using the cam-shaft.

Installation

To use the Cam-Shaft, you can install the npm package in your project. Alternatively you can load the script from one of the global content delivery networks that provide npm packages.

Using the npm package
Loading the script from a CDN

Install @vtbag/cam-shaft@latest from npm.
In your project, add @vtbag/cam-shaft/index.js as an inline script at the beginning of the <head> element on all pages of your site.

Details depend on your project setup and the frameworks used, but it can be as simple as:

import shaft from "@vtbag/cam-shaft?url";
<html>
  <head>
    <script src={shaft} />
    ...
  </head>
  ...
</html>;

You can load the script from CDNs such as jsdelivr.net or unpkg.com. Place the script inline at the beginning of the <head> element on all pages where you need avoid pseudo-smooth-scrolling.

Using jsdeliver.net:

<html>
  <head>
    <script src="https://cdn.jsdelivr.net/npm/@vtbag/cam-shaft" />
    ...
  </head>
  ...
</html>

or alternatively using unpkg.com:

<html>
  <head>
    <script src="https://unpkg.com/@vtbag/cam-shaft" />
    ...
  </head>
  ...
</html>

Configuration and Usage

The Cam-Shaft script needs to know which view transition name’s images it should bump and nudge. By default, it assumes it should handle ::view-transition-group(main).

If you need to target a different view transition name, you can use the data-view-transition-names attribute in the script tag. For example, the following will instruct the script to handle images for ::view-transition-group(content):

<script src=... data-view-transition-names="content"/>

As you may have guessed from the plural form, you can specify multiple view transition names by separating them with spaces, allowing the script to manage several groups.