Introducing view-transitions-mock: A non-visual Polyfill for Same-Document View Transitions

~

The Challenge: Writing Future-Proof Code

When using new APIs like the View Transition API, you need to write defensive code that check for browser support:

if (!document.startViewTransition) {
  updateTheDOM();
} else {
  document.startViewTransition(updateTheDOM);
}

This clutters your codebase with if (document.startViewTransition) guards which makes it harder to maintain. And that list of safeguards quickly grows, for example when you throw View Transition Types in the mix.

~

The Solution: view-transitions-mock

Ideally, you want to write code that will work seamlessly in all browsers, regardless of whether they support Same-Document View Transitions natively or not. The bridge that gap I created view-transitions-mock, a non-visual polyfill that mocks the entire JavaScript API surface of Same-Document View Transitions, including:

• document.startViewTransition()
• The ViewTransition class, including:
  • The updateCallbackDone, ready, and finished promises.
  • The ViewTransition.transitionRoot property.
• document.activeViewTransition
• View Transition Types

What it doesn’t polyfill are the visual aspects: the pseudo-tree, the CSS properties, and the animations themselves. This means that while you won’t see any animations in browsers without native support, yet your code will still execute without errors, and the DOM will be updated as expected.

~

Getting Started

Using view-transitions-mock is incredibly simple. First, install it from npm:

npm i view-transitions-mock

Then, import and register it in your code (before calling document.startViewTransition):

import { register } from "view-transitions-mock";
register();

That’s it! You can now use the View Transition API without any worries.

import { register } from "view-transitions-mock";
register();

document.startViewTransition(() => {
  // …
});

~

Tweaking the registration

By default, the registration of view-transitions-mock checks whether document.startViewTransition and View Transition Types are supported or not. When both are natively supported, it won’t register the mock.

You can tweak the registration by passing an object with the following properties into the register function:

• requireTypes (Boolean, default value: true): Require support for View Transition Types
• forced (Boolean, default value: false): Force register the mock, regardless of support.

For example, if you are not relying on View Transition Types, call register as follows so that it does not register the mock in Firefox 144–146 (which does not have support for View Transition Types):

import { register } from "view-transitions-mock";
register({ requireTypes: false });

Or if you want to disable native support for Same-Document View Transitions entirely – handy if you want to test how your site looks without View Transitions – call register as follows:

import { register } from "view-transitions-mock";
register({ forced: true });

~

See it in Action

Over at https://chrome.dev/view-transitions-mock you can find a live demo of view-transitions-mock. Every time you click the area around the box a View Transition gets started and output is added to the log.

By default won’t see much happening in the demo, because the thing that you should be seeing is that it doesn’t crash in browsers with no support for Same-Document View Transitions. You can use one of the buttons on the page to do a forced registration of view-transitions-mock. After having done so, you’ll see stuff get added to the log, but no visual transition happening. This is the view-transitions-mock in action!

The source code for the demo is also available in the repository.

~

To learn more about view-transitions-mock, check out the following links if you haven’t done so already:

• view-transitions-mock Source (GitHub) →
• view-transitions-mock Demo →
• view-transitions-mock on NPMJS →
• view-transitions-mock on npmx →

~