CSS view-transition-name Property

The view-transition-name property assigns a unique identifier to an element, allowing the browser to track and animate it across DOM changes.

selector { view-transition-name: <custom-ident> | none; }
none The element will not be assigned a specific name and will participate in the default cross-fade transition if applicable.
<custom-ident> A unique, developer-defined name used to identify and connect the element between different states of a transition.

Code Examples

A basic example showing how to tag a header element with a unique transition name.

<style>
.hero-header {
  view-transition-name: main-title;
  background-color: #0077ff;
  color: #ffffff;
  padding: 20px;
}
</style>
<h1 class="hero-header">My Website Title</h1>
<p>This heading will smoothly transition its position and size if the browser finds another element with the same view-transition-name in the next state.</p>

Advanced example using JavaScript to trigger a transition while dynamically assigning the view-transition-name to a specific element.

<style>
  .box {
    width: 100px;
    height: 100px;
    background: #ff5500;
  }
  .big {
    width: 300px;
    height: 300px;
    margin-top: 50px;
  }
</style>

<div id="item" class="box"></div>
<button onclick="toggleSize()">Toggle Transition</button>

<script>
function toggleSize() {
  const el = document.getElementById("item");
  // Apply name dynamically to avoid conflicts elsewhere
  el.style.viewTransitionName = "moving-box";

  if (!document.startViewTransition) {
    el.classList.toggle("big");
    return;
  }

  document.startViewTransition(() => {
    el.classList.toggle("big");
  });
}
</script>

Pro Tip

You can use the same name for different elements as long as they aren't in the DOM at the same time. This is perfect for 'shared element' transitions where a small thumbnail on one page becomes a large hero image on the next. Since they never exist on the screen together, they can safely share the same identity tag.

Deep Dive

Think of this property like a luggage tag at an airport. When you change the page or update the DOM, you slap a unique tag on an element. The browser sees that tag on both the old state and the new state, realizing they are actually the same piece of 'luggage.' Instead of just popping the element into existence at the new location, the browser automatically calculates the movement, scale, and opacity changes to slide it smoothly from point A to point B. It creates a pseudo-element tree specifically for the transition, where your named element becomes a hero of the animation sequence. Without this name, the browser has no way of knowing which element is which during the shuffle, resulting in a simple fade or no animation at all.

Best Practices

Only assign a name to elements that actually need to transition smoothly. Keep names unique across the entire page; if two visible elements share the same name, the transition will fail to execute. For dynamic lists, avoid hardcoding names in your CSS. Instead, use inline styles or JavaScript to apply the name only to the element being interacted with, ensuring the browser doesn't get confused by duplicate identifiers.

Common Pitfalls

The biggest mistake is having duplicate names on the page at the same time, which causes the transition to be skipped. Developers also frequently forget that this property only works when the state change is wrapped inside a document.startViewTransition call in JavaScript. Also, remember that the element must be visible; if it is hidden or has a display value of none, the transition name will not be captured for the snapshot.

Accessibility

Animations can cause discomfort for users with motion sensitivities. Always respect the user's system preferences by wrapping your transition styles or logic in a prefers-reduced-motion media query. If a user prefers reduced motion, you should either disable the transition or simplify it to a basic fade that doesn't involve heavy movement across the screen.

Dev Data Table: view-transition-name property

default none
animatable no
inherited no
experimental yes
year_intro 2023
year_standard 0
js_syntax_1 element.style.viewTransitionName = "main-image";
js_syntax_2 element.style.setProperty("view-transition-name", "main-image");
js_note Ensure the name is unique within the document during the transition to avoid errors.
browsers { "Chrome": 111, "Edge": 111, "Firefox": 0, "Safari": 18, "Opera": 97, "Chrome Android": 111, "Safari on iOS": 18, "Samsung Internet": 22, "Opera Mobile": 97 }
results render here...