tailwindcss-view-transitions

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

Installation

npm install -D tailwindcss-view-transitions

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

// 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.

<div class="vt-name-[main-content]">
</div>

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

<div class="vt-name-[main-content] md:vt-name-none">
</div>

<div class="vt-name-[main-content] motion-reduce:vt-name-none">
</div>

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-[main-content]	view-transition-name: main-content;
vt-name-none	view-transition-name: none;

Styling with CSS

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

/* 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: ... */
}

Configuration

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

// 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.

disableAllReduceMotion

• 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:

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

styles

• Type: Record<string, CSSRuleObject & { old?: CSSRuleObject; new?: CSSRuleObject }>
• 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.