/tailwindcss-view-transitions

TailwindCSS plugin for customizing styles for the View Transitions Web API

Primary LanguageJavaScriptMIT LicenseMIT

tailwindcss-view-transitions

NPM package version

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.