🔄 Mastering view-transition-name in CSS

📌 What Is view-transition-name?

The view-transition-name property is part of the modernCSS View Transitions API, which allows smooth animated transitions when switching between pages, states, or UI views — without JavaScript-heavy solutions. ⚡✨
It assigns a unique identifier to an element so the browser can match it across UI updates and animate the difference.

>>“View transitions let the browser animate DOM changes — effortlessly and beautifully.”

🎯 Why Use view-transition-name?

  • Smooth page transitions without SPAs
  • Animate elements between states automatically
  • Reduce JavaScript complexity
  • Great for dynamic UI, toggles, light/dark mode transitions, etc.

🧩 Basic Syntax

Syntax

view-transition-name: myTransitionElement;

🔥 Important Rules

  • You must enable document.startViewTransition() in JS
  • Elements must have the SAME view-transition-name before and after the change
  • The browser automatically animates differences
  • Names must be unique per element

🧪 Basic Example

HTML

HTML

<h1 id="title" view-transition-name="main-title">Hello</h1>
<button id="change">Change Text</button>

CSS

CSS

h1 {
  view-transition-name: main-title;
}

JS

JavaScript

document.getElementById('change').onclick = () => {
  document.startViewTransition(() => {
    document.getElementById('title').textContent = 'Welcome!';
  });
};

✔ The browser animates the old text to the new text smoothly.

🎨 Styling the Transition

A view transition creates three pseudo-elements you can style:

  • ::view-transition-old() – before state
  • ::view-transition-new() – after state
  • ::view-transition-group() – container for both

Styling Transition Layers

::view-transition-old(main-title),
::view-transition-new(main-title) {
  animation: fade 0.4s ease;
}

@keyframes fade

@keyframes fade {
  from { opacity: 0; }
  to   { opacity: 1; }
}

✔ Customize how elements fade, slide, scale, or blur during transitions.

📦 Example: Card Switching Animation

HTML

HTML

<div class="card" view-transition-name="info-card">Content A</div>
<button id="swap">Swap</button>

JS

JavaScript

const card = document.querySelector('.card');

document.querySelector('#swap').onclick = () => {
  document.startViewTransition(() => {
    card.textContent =
      card.textContent === 'Content A' ? 'Content B' : 'Content A';
  });
};

CSS

CSS

.card {
  view-transition-name: info-card;
  padding: 20px;
  border-radius: 12px;
  background: #222;
  color: white;
}

::view-transition-new(info-card) {
  animation: cardEnter 0.4s ease-out;
}

@keyframes cardEnter {
  from { opacity: 0; transform: scale(0.9); }
  to   { opacity: 1; transform: scale(1); }
}

✔ Creates a smooth transition between the two card contents.

🌗 Dark Mode Toggle Example

JS

toggleBtn.onclick = () => {
  document.startViewTransition(() => {
    document.documentElement.classList.toggle('dark');
  });
};

CSS

html {
  view-transition-name: page-theme;
}

::view-transition-old(page-theme),
::view-transition-new(page-theme) {
  animation: themeSwap 0.3s ease-in-out;
}

@keyframes themeSwap {
  from { filter: brightness(0.4); }
  to   { filter: brightness(1); }
}

✔ Smooth, polished theme switching out-of-the-box.

🧠 Tips & Best Practices

  • Assign unique transition names for each animating element
  • Use startViewTransition() to wrap DOM updates
  • Don’t animate huge elements unless necessary (performance)
  • Style pseudo-elements for full control
  • Avoid transitions for rapidly changing elements

🔍 Debugging Tips

  • If animation doesn’t happen: check if view-transition-name matches exactly
  • Ensure transitions are triggered inside startViewTransition()
  • View transitions only work on elements inside the updated DOM tree
  • Make sure your browser supports the View Transitions API

🔗 Helpful Resources

>>“view-transition-name unlocks native page transitions — smooth, automatic, magical.” ✨