View Transitions API polyfill

A polyfill for the View Transitions API.

The polyfill is available on NPM.

Star this repo ⭐ on GitHub if you found it helpful!

Demo

View some demos showing example transitions.

Installation

Using npm

Install the polyfill in your project from npm:

npm install view-transitions-polyfill

Plain JS file

You may also download the polyfill's pre-built JS file from:

• Download version 1.0.5 (obtained from the latest GitHub release)

jsDelivr CDN

Get the polyfill from from jsDelivr:

• Version 1.0.5: https://cdn.jsdelivr.net/npm/[email protected]
• Latest version: https://cdn.jsdelivr.net/npm/view-transitions-polyfill

Usage

Import the module into your site.

Inside a script (make sure it has type="module" in the <script> tag):

import 'view-transitions-polyfill';

Or from the HTML:

<script src="view-transitions-polyfill" async></script>

<!-- If the above does not work, try: -->
<script type="module">
  import 'view-transitions-polyfill';
</script>

[!NOTE]
Change the URLs in the above code snippets according to your use case.

• Import from npm: view-transitions-polyfill
• Import from plain JS file: ./view-transitions-polyfill.js (point it to the correct path for you)
• Import from jsDelivr (version 1.0.5): https://cdn.jsdelivr.net/npm/[email protected]

Conditional loading

The above code snippets will always download the polyfill, whether the browser needs it or not. In order to only download the polyfill when needed, use the following code snippets.

Inside a script (make sure it has type="module" in the <script> tag):

if (!document.startViewTransition) {
  import('view-transitions-polyfill');
}

Or from the HTML:

<script type="module">
  if (!document.startViewTransition) {
    import('view-transitions-polyfill');
  }
</script>

[!NOTE]
Change the URLs in the above code snippets according to your use case.

• Import from npm: view-transitions-polyfill
• Import from plain JS file: ./view-transitions-polyfill.js (point it to the correct path for you)
• Import from jsDelivr (version 1.0.5): https://cdn.jsdelivr.net/npm/[email protected]

With Astro View Transitions

You can use the polyfill with Astro view transitions by importing the script in the document as you would normally. For example, within a component:

<script src="view-transitions-polyfill"></script>

Compatibility

According to data from Can I use, the polyfill should be fully supported on:

• Chrome ≥ 88
• Edge ≥ 88
• Opera ≥ 74
• Safari ≥ 14
• Firefox ≥ 78

This is because the polyfill currently requires the browser to support these notable features:

• Element.animate()
• Document.getAnimations()
• requestAnimationFrame()
• Custom elements
• Shadow DOM
• CSS :where() selector

Development

Building

Build the polyfill to dist:

npm run build

Testing

To test the polyfill, you can run Web Platform Tests. You need to set up your system before running tests.

Run the tests with:

npm run test

This will generate report files in test/report.

The polyfill only loads its functions into the browser if it does not already natively support the View Transitions API. You can run the tests with a version of the polyfill that avoids this check with:

npm run test-always-polyfill

You can view the tests' web pages in your browser with:

npm run test-debug

Optimizing test performance

It is recommended that you run the tests like this:

npm run test -- --processes <number of threads> -f --exclude css/css-view-transitions/navigation

• --processes and -f introduce parallelism to make the tests run faster.
• --exclude makes it so that Navigation API tests are ignored, since they will always fail on some browsers (e.g. Firefox) which do not implement that API.

[!NOTE] More command line options are documented on the web platform tests documentation.

You can also add these arguments to npm run test-always-polyfill.

Performance measurement

A version of the polyfill set up to measure its performance can be found at the performance branch. You can follow the associated instructions.