Rege
view-transitionsjavascriptchrome1 min read

Scoped View Transitions

Run view transitions on DOM subtrees instead of the whole document

Rege

@rege_dev

Scoped View Transitions is a proposed extension to the View Transition API that lets you start a view transition on a subtree of the DOM instead of the whole document. This enables multiple simultaneous transitions and keeps animations clipped within their containers.

Read more on Chrome Developers →

Basic Usage

Instead of calling document.startViewTransition(), call element.startViewTransition() on any HTMLElement with contain: layout applied.

JavaScript

// Element must have contain: layout
.container {
  contain: layout;
}

// Start a scoped view transition
document.querySelector('.container').startViewTransition({
  update: () => {
    // ... code that manipulates the contents
  },
});

Pseudo-element Structure

The ::view-transition pseudo-tree gets injected onto the scoped element rather than the document root:

Text

html
  └─ body
     ├─ nav
     │  ├─ ::view-transition
     │  │  └─ ::view-transition-group(thing)
     │  │     └─ ::view-transition-image-pair(thing)
     │  │        ├─ ::view-transition-old(thing)
     │  │        └─ ::view-transition-new(thing)
     │  └─ ul
     │     └─ ...
     └─ main
        └─ ...

Key Benefits

  • Multiple simultaneous transitions: Different parts of your UI can animate independently as long as they have different transition roots.
  • Scoped pointer events: Pointer events are only prevented on the transitioning subtree, not the whole document.
  • Proper layering: Elements outside the transition root (like popovers) can paint on top of the scoped view transition.

Interactive Demo

Compare how document-scoped and element-scoped transitions behave differently. With scoped transitions, the animated element stays clipped within its container.

Click the buttons to move the dot. Toggle between transition types to see how scoped transitions keep the animation clipped within the container.

Transition:

Document-scoped

Uses document.startViewTransition(). The dot may animate outside the container bounds and paint over other elements like popovers.

Element-scoped

Uses element.startViewTransition(). The dot stays clipped within its container during the transition.

Further Reading

Filed underview-transitionsjavascriptchrome

Written by Rege

Building CoAnimator & YourGPT. Notes and updates on X.

Follow

© 2026 rege. All rights reserved.