CSS view-transition-name Property

Description

The view-transition-name property lets you mark an element with an identifier that the View Transitions system uses to detect and produce shared-element transitions between two visual states. When a navigation or view change occurs that is wrapped by the View Transitions machinery (for example via the JavaScript API), elements that carry the same computed view-transition-name across the outgoing and incoming views can be matched together so the UA can capture snapshots and animate continuity between them. This makes it possible to produce smooth “move/resize/fade” effects that visually carry an element from one layout to the next rather than having it abruptly disappear and reappear.

Matching is done by comparing the logical name on elements in the two snapshots; the property is used as a key rather than relying on DOM identity or id attributes. Once a match is found, the browser creates transient visual layers (snapshots) for those matched elements and animates differences in geometry, transform, opacity, clipping and other visual characteristics to produce the shared-element effect. Because the implementation works with visual snapshots, layout differences, stacking context, and compositing can affect the result - placing the name on an element that has a stable box and predictable stacking will produce more reliable animations than naming heavily dynamic or reflowing elements.

From a practical perspective, developers use view-transition-name to opt specific elements into view transitions and combine it with other transition/animation techniques. For example, the UA’s snapshot/animation process can interact with normal CSS transitions and animations, so be mindful of how those might overlap; in many cases the browser’s view-transition animation takes precedence for the shared element snapshot while other transitions continue to run on non-matched properties. Also consider interaction with the transient styling hooks the View Transitions spec exposes (such as the pseudo-elements used for the intermediate images) and follow accessibility guidance - provide fallbacks or avoid complex motion when users prefer reduced motion. For typical use, mark a limited set of stable, visually prominent elements (images, avatars, cards) to keep animations performant and predictable; excessive or frequently changing names can lead to heavy snapshotting and jank.

Definition

Initial value: none
Applies to: all elements
Inherited: no
Computed value: as specified
Animatable: yes
JavaScript syntax: object.style.viewTransitionName

Syntax

view-transition-name: none | <custom-ident>;

Values

noneIndicates that the element should not participate in view transitions.
<custom-ident>A custom identifier (any valid CSS identifier) that assigns a transition name to the element.

Example

HTML

<div class="app">

    <div class="gallery">

        <h1>Gallery (click on image)</h1>

        <div class="grid">

            <img src="https://picsum.photos/id/1015/300/200" alt="Mountains" class="thumb hero" />

            <img src="https://picsum.photos/id/1025/300/200" alt="Horse" class="thumb hero" />

            <img src="https://picsum.photos/id/1035/300/200" alt="Forest" class="thumb hero" />

        </div>

    </div>



    <div class="detail hidden">

        <button class="back">← Back</button>

        <div class="frame">

            <img src="" alt="Detail" class="hero" />

        </div>

    </div>

</div>



<script>

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

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

    const detailImg = detail.querySelector('img');



    gallery.querySelector('.grid').addEventListener('click', (e) => {

        const img = e.target.closest('img');

        if (!img) return;

        const src = img.src;



        const swap = () => {

            gallery.classList.add('hidden');

            detailImg.src = src;

            detail.classList.remove('hidden');

        };



        if (document.startViewTransition) {

            document.startViewTransition(swap);

        } else {

            swap();

        }

    });



    document.querySelector('.back').addEventListener('click', () => {

        const swap = () => {

            detail.classList.add('hidden');

            gallery.classList.remove('hidden');

        };



        if (document.startViewTransition) {

            document.startViewTransition(swap);

        } else {

            swap();

        }

    });

</script>

CSS

/* Layout and basic styles */
.app {
    font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial;
    max-width: 900px;
    margin: 32px auto;
    padding: 0 16px;
}

.grid {
    display: flex;
    gap: 16px;
}

.thumb {
    width: 300px;
    height: 200px;
    object-fit: cover;
    cursor: pointer;
    border-radius: 12px;
    box-shadow: 0 6px 18px rgba(0, 0, 0, 0.12);
}

/* Assign a view-transition-name so the same visual element in both states is matched */
.hero {
    view-transition-name: hero;
}

/* Detail view */
.detail {
    display: flex;
    flex-direction: column;
    align-items: center;
    gap: 16px;
}

.detail .frame {
    width: 80%;
    max-width: 700px;
}

.detail img {
    width: 100%;
    height: auto;
    border-radius: 6px;
    box-shadow: 0 8px 28px rgba(0, 0, 0, 0.18);
}

.hidden {
    display: none;
}

/* Animate the shared element during view transitions using the name 'hero' */
::view-transition-old(hero),
::view-transition-new(hero) {
    /* animate transform, border-radius and shadow for a smooth hero-image transition */
    transition: transform 420ms cubic-bezier(.2, .8, .2, 1),
                border-radius 420ms cubic-bezier(.2, .8, .2, 1),
                box-shadow 420ms;
    transform-origin: center;
    box-shadow: 0 12px 30px rgba(0, 0, 0, 0.18);
}

/* Optional: style the image snapshot used during the transition */
::view-transition-image(hero) {
    border-radius: 10px;
    filter: drop-shadow(0 12px 24px rgba(0, 0, 0, 0.15));
}

Result

Editor

Browser Support

The following information will show you the current browser support for the CSS view-transition-name property. Hover over a browser icon to see the version that first introduced support for this CSS property.