You have implemented the View Transitions API to animate a list filtering or reordering operation. The logic seems sound: you wrap your state update in document.startViewTransition, and you assign a dynamic view-transition-name to each list item.
But instead of a smooth morph, the screen snaps instantly to the new state. In your console, you see the death knell of the animation:
Aborting view transition: duplicate view-transition-name 'card-123' found.
This error is a hard stop. The browser refuses to guess which DOM node "owns" the transition name. In complex React applications—especially those using responsive layouts or dashboard patterns—this is the single most common implementation hurdle.
Here is the root cause analysis and a production-grade solution to guarantee uniqueness without sacrificing code maintainability.
The Why: Global Namespace vs. Component Isolation
The View Transitions API relies on a flat, global namespace. view-transition-name acts like an HTML id: it must be unique across the entire document tree at the moment the transition snapshot is taken.
React developers, however, are trained to think in components, not global trees. We encounter duplication errors usually due to three scenarios:
- Responsive Duplication: You render a "Mobile List" and a "Desktop Grid" of the same data, hiding one with CSS (
display: none). While hidden elements are often ignored by the snapshot, elements that are merely obscured, off-canvas, or in a "loading" state often retain their computed styles. - Cross-Reference Widgets: The same item (
id: 123) appears in the main list and in a "Recently Viewed" sidebar. Both instances attempt to claimview-transition-name: item-123. - React Key/Index Anti-patterns: Using array indices for names (
item-0,item-1) during a reorder. If the DOM doesn't update synchronously with the snapshot, the browser might see the "old"item-0and the "new"item-0co-existing in a way that violates uniqueness constraints during the transition setup.
To fix this, we must enforce Scoped Uniqueness. We cannot simply derive the transition name from the data ID; we must derive it from the context in which that data is rendered.
The Fix: Scoped Transition Names
We will implement a ScopedViewTransition pattern. This involves a custom hook to generate namespaced identifiers and a strictly typed component structure to ensure your lists never collide.
1. The Hook: useScopedTransitionName
This hook ensures that every transition name is prefixed with a context identifier.
// hooks/useScopedTransitionName.ts
import { useMemo } from 'react';
/**
* Generates a globally unique view-transition-name based on a scope and entity ID.
*
* @param scope - A unique string identifier for the container (e.g., 'main-grid', 'sidebar').
* @param id - The unique ID of the data entity.
* @returns A sanitized string ready for the 'view-transition-name' CSS property.
*/
export function useScopedTransitionName(scope: string, id: string | number): string {
return useMemo(() => {
// Sanitize the input to ensure valid CSS identifiers
const safeScope = scope.replace(/[^a-zA-Z0-9-_]/g, '-');
const safeId = String(id).replace(/[^a-zA-Z0-9-_]/g, '-');
// Format: [scope]__[entity-id]
return `vt-${safeScope}__${safeId}`;
}, [scope, id]);
}
2. Implementing the List Component
Here is a modern Next.js/React component implementing the fix. Note the usage of flushSync. React 18+ batches state updates asynchronously. The View Transitions API requires the DOM change to happen inside the callback. We use flushSync to force React to apply the DOM updates immediately, ensuring the "After" snapshot matches the new state.
// components/ProductList.tsx
'use client';
import { useState } from 'react';
import { flushSync } from 'react-dom';
import { useScopedTransitionName } from '@/hooks/useScopedTransitionName';
interface Product {
id: string;
name: string;
category: string;
}
interface ProductListProps {
products: Product[];
scopeId: string; // CRITICAL: Must be unique per instance of this component
}
export const ProductList = ({ products: initialProducts, scopeId }: ProductListProps) => {
const [items, setItems] = useState(initialProducts);
const filterCategory = (category: string) => {
// 1. Check if the browser supports the API
if (!document.startViewTransition) {
setItems(initialProducts.filter((p) => p.category === category));
return;
}
// 2. Start the transition
document.startViewTransition(() => {
// 3. Force synchronous DOM update so the browser can snap the 'new' state
flushSync(() => {
setItems(initialProducts.filter((p) => p.category === category));
});
});
};
return (
<section className="p-4">
<div className="mb-4 flex gap-2">
<button onClick={() => filterCategory('electronics')} className="btn">
Filter Electronics
</button>
<button
onClick={() => {
// Reset handler
if (!document.startViewTransition) {
setItems(initialProducts);
return;
}
document.startViewTransition(() => {
flushSync(() => setItems(initialProducts));
});
}}
className="btn"
>
Reset
</button>
</div>
<ul className="grid grid-cols-1 md:grid-cols-3 gap-4">
{items.map((product) => (
<ProductCard
key={product.id}
product={product}
scopeId={scopeId}
/>
))}
</ul>
</section>
);
};
// Sub-component handling the style application
const ProductCard = ({ product, scopeId }: { product: Product; scopeId: string }) => {
// Generate the unique name: e.g., "vt-main-grid__101"
const transitionName = useScopedTransitionName(scopeId, product.id);
return (
<li
className="p-6 border rounded-lg shadow-sm bg-white"
style={{
// Apply the dynamic name via inline styles
viewTransitionName: transitionName,
// Ensure the element has its own layer to prevent painting issues
contain: 'layout paint',
}}
>
<h3 className="font-bold text-lg">{product.name}</h3>
<p className="text-gray-500">{product.category}</p>
</li>
);
};
3. Usage: Preventing Collisions
Now, if you render this list in multiple places, you simply pass a different scopeId.
// app/dashboard/page.tsx
import { ProductList } from '@/components/ProductList';
export default function DashboardPage() {
const data = await fetchProducts(); // Server Component data fetching
return (
<main>
<h1>Inventory</h1>
{/* Main interactive grid */}
<ProductList products={data} scopeId="main-inventory" />
{/*
Even if we render the same data in a 'Preview' modal or sidebar,
the transition names will be 'vt-sidebar__101' vs 'vt-main-inventory__101'.
No collision. No crash.
*/}
<aside className="hidden lg:block">
<ProductList products={data.slice(0, 5)} scopeId="sidebar-featured" />
</aside>
</main>
);
}
The Explanation
Why does this solve the problem so effectively?
- Namespace Segregation: By forcing a
scopeIdprop, we acknowledge that while the data (the Product) is the same, the DOM representation is distinct. The browser needs to know specifically which DOM node moves where. If we want to animate the Main Inventory list, we don't want the browser confused by the Sidebar list. flushSyncCompliance: React's batching is the enemy ofstartViewTransition. WithoutflushSync, the callback passed tostartViewTransitionfinishes execution before React commits the changes to the DOM. The browser takes the "After" snapshot, sees nothing has changed, and abandons the transition.flushSyncforces the React commit phase to complete synchronously within the transition callback.- Containment: Adding
contain: layout paint(or specificallycontain: paint) is a CSS best practice for view transitions. It helps the browser isolate the element's geometry, preventing layout thrashing when the element is promoted to a "snapshot layer."
Conclusion
The view-transition-name property is powerful, but it is global mutable state. In a component-based architecture like React, treating it as such is dangerous.
By treating transition names as tuples of (Context, EntityID) rather than just EntityID, you eliminate collision errors entirely. You can now filter, sort, and reorder your lists with confidence, knowing that the browser can deterministicly match the old and new states of your interface.