# Scoped View Transitions

> Run view transitions on DOM subtrees instead of the whole document

Published: 2024-12-04  
Tags: view-transitions, javascript, chrome  
Source: https://www.rege-dev.xyz/writing/scoped-view-transitions

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 →](https://developer.chrome.com/blog/scoped-view-transitions-feedback)

**Experimental feature**
  Scoped View Transitions require Chrome 140+ with the “Experimental Web Platform features” flag enabled in `chrome://flags`.

## 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.

_Interactive demo: https://www.rege-dev.xyz/writing/scoped-view-transitions_

## Further Reading

- [Next.js viewTransition Config](https://nextjs.org/docs/app/api-reference/config/next-config-js/viewTransition)
- [MDN: View Transition API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API)
- [React: addTransitionType](https://react.dev/reference/react/addTransitionType)
