tailwindcss-view-transitions


A plugin for customizing styles for the View Transitions Web API.

Installation

``sh
npm install -D tailwindcss-view-transitions
`

Then add the plugin to your tailwind.config.js file:

`js
// tailwind.config.js
module.exports = {
theme: {
// ...
},
plugins: [
require("tailwindcss-view-transitions"),
// ...
],
}
`

Usage

Use the vt-name-[ANY_STRING] utility class to create a separate view transition on specific elements.

`html


Use vt-name-none to disable a view transition. Can be used with any Tailwind variant, such as md:*.

`html


The name can be any string except root (❌ vt-name-[root]), which is reserved for the default top-level view transition.

| Class | CSS properties |
| --- | --- |
| vt-name-[foo] | view-transition-name: foo; |
| vt-name-[foo-bar] | view-transition-name: foo-bar; |
| vt-name-none | view-transition-name: none; |

$3

Style the view transition pseudo-elements from your global CSS file.

`css
/ input.css /
@tailwind base;
@tailwind components;
@tailwind utilities;

::view-transition-old(root),
::view-transition-new(root) {
animation: none;
}

::view-transition-old(main-content) {
/ Add custom animation or style here /
/ animation: ... /
}

::view-transition-new(main-content) {
/ Add custom animation or style here /
/ animation: ... /
}
`

$3

Alternatively, you can define styles from plugin configuration in your tailwind.config.js file.

`js
// tailwind.config.js
module.exports = {
plugins: [
require("tailwindcss-view-transitions")({
disableAllReduceMotion: false,
styles: {
// ...
},
}),
// ... other plugins
],
}
`

Options

The plugin config accepts an options object as argument which contains these properties. All are optional.

$3

- Type: boolean
- Default: false

Disables _all_ view transitions animation if user has set preference for reduced motion. (Note: Consider this point before disabling animations completely.)

If true, it applies this code globally:

`css
@media (prefers-reduced-motion) {
::view-transition-group(),::view-transition-old(),::view-transition-new(*) {
animation: none !important;
}
}
`

$3

- Type: Record
- Default: {}

Defines CSS styles for the view transition pseudo-elements.

The styles object may contain any number of properties.

- The key is the view transition name (root or any string value assigned here)
- The value is one or more of these:
- a CSS rule object, which will be applied to both outgoing (::view-transition-old(VT_NAME)) and incoming (::view-transition-new(VT_NAME)) pseudo-elements
- a propery old containing a CSS rule object, which will be applied only to ::view-transition-old(VT_NAME)
- a propery new containing a CSS rule object, which will be applied only to ::view-transition-new(VT_NAME)

| styles config | Generated CSS |
| --- | --- |
|

{ 
  root: { animation: "none" },
}

::view-transition-old(root),
::view-transition-new(root) {
  animation: none;
}

{ 
  root: { 
    old: { animationDuration: "1s" },
    new: { animationDuration: "3s" },
  },
}

::view-transition-old(root) {
  animation-duration: 1s;
}
::view-transition-new(root) {
  animation-duration: 3s;
}

{ 
  root: { animation: "none" },
  "main-content": { 
    old: { animationDuration: "1s" },
    new: { animationDuration: "3s" },
  },
}

::view-transition-old(root),
::view-transition-new(root) {
  animation: none;
}

::view-transition-old(main-content) {
  animation-duration: 1s;
}
::view-transition-new(main-content) {
  animation-duration: 3s;
}

⚠️ If applying custom CSS animation, you need to define @keyframes separately in your CSS file or through Tailwind theme configuration, or alternatively use an existing @keyframes` animation.

Detailed examples: https://github.com/ekafyi/tailwindcss-view-transitions/blob/main/docs/examples.md

When not to use?

You may not need this plugin if:

* You don’t need to customize the default browser transition styles
* You do styling outside of Tailwind configuration
* You exclusively use a (meta)framework that has its own API for conveniently styling view transitions, such as Astro

As an unofficial plugin, it will be deprecated when/if Tailwind adds an official plugin for styling view transitions.

Bugs & feature requests

While I'm not actively accepting feature requests, I outlined future plans in the Discussions.

Found a bug? Feel free to open an issue.