Patterns and Guidelines

Searchable Grid with useDeferredValue

useDeferredValue makes filter updates a transition, activating ``:

'use client';

  const [search, setSearch] = useState('');
  const deferredSearch = useDeferredValue(search);

  return (
    <>
      <input value={search} onChange={(e) => setSearch(e.currentTarget.value)} />
      
        }>
          
        
      
    </>
  );
}

Per-item `` inside a deferred list triggers cross-fades on every keystroke. Fix with default="none":

{filteredItems.map(item => (
  
    
  
))}

Card Expand/Collapse with startTransition

Toggle between grid and detail view with shared element morph:

'use client';

  const [expandedId, setExpandedId] = useState(null);
  const scrollRef = useRef(0);

  return expandedId ? (
    
       i.id === expandedId)}
        onClose={() => {
          startTransition(() => {
            setExpandedId(null);
            setTimeout(() => window.scrollTo({ behavior: 'smooth', top: scrollRef.current }), 100);
          });
        }}
      />
    
  ) : (
    <div className="grid grid-cols-3 gap-4">
      {items.map(item => (
        
           {
              scrollRef.current = window.scrollY;
              startTransition(() => setExpandedId(item.id));
            }}
          />
        
      ))}
    </div>
  );
}

Type-Safe Transition Helpers

Use as const arrays and derived types to prevent ID clashes:

const transitionTypes = ['default', 'transition-to-detail', 'transition-to-list'] as const;
const animationTypes = ['auto', 'none', 'animate-slide-from-left', 'animate-slide-from-right'] as const;

type TransitionType = (typeof transitionTypes)[number];
type AnimationType = (typeof animationTypes)[number];
type TransitionMap = { default: AnimationType } & Partial<Record<Exclude<TransitionType, 'default'>, AnimationType>>;

  children: React.ReactNode;
  enter: TransitionMap;
  exit: TransitionMap;
}) {
  return {children};
}

Cross-Fade Without Remount

Omit key to trigger an update (cross-fade) instead of exit + enter. Avoids Suspense remount/refetch:

Use key when content identity changes (state resets). Omit for cross-fades (tabs, panels, carousel).

Isolate Elements from Parent Animations

Persistent Layout Elements

Persistent elements (headers, navbars, sidebars) get captured in the page's transition snapshot. Fix with viewTransitionName:

<nav style={{ viewTransitionName: "persistent-nav" }}></nav>

::view-transition-group(persistent-nav) {
  animation: none;
  z-index: 100;
}

For backdrop-blur/backdrop-filter, see Backdrop-Blur Workaround in css-recipes.md.

Floating Elements

Give popovers/tooltips their own viewTransitionName:

{options}

Global fix: ::view-transition-group(*) { z-index: 100; }

Shared Controls Between Skeleton and Content

Give matching controls in fallback and content the same viewTransitionName:

// Fallback
<input disabled placeholder="Search..." style={{ viewTransitionName: 'search-input' }} />
// Content
<input placeholder="Search..." style={{ viewTransitionName: 'search-input' }} />

Don't put manual viewTransitionName on the root DOM node inside `` — React's auto-generated name overrides it.

Reusable Animated Collapse

function AnimatedCollapse({ open, children }) {
  if (!open) return null;
  return (
    
      {children}
    
  );
}

// Usage: toggle with startTransition
<button onClick={() => startTransition(() => setOpen(o => !o))}>Toggle</button>

Preserve State with Activity

Exclude Elements with useOptimistic

useOptimistic values update before the transition snapshot, excluding them from animation. Use for controls (labels); use committed state for animated content:

const [sort, setSort] = useState('newest');
const [optimisticSort, setOptimisticSort] = useOptimistic(sort);

function cycleSort() {
  const nextSort = getNextSort(optimisticSort);
  startTransition(() => {
    setOptimisticSort(nextSort);  // before snapshot — no animation
    setSort(nextSort);            // between snapshots — animates
  });
}

<button>Sort: {LABELS[optimisticSort]}</button>
{items.sort(comparators[sort]).map(item => (
  
))}

---

View Transition Events

Imperative control via onEnter, onExit, onUpdate, onShare. Always return a cleanup function. onShare takes precedence over onEnter/onExit.

 {
    const anim = instance.new.animate(
      [{ transform: 'scale(0.8)', opacity: 0 }, { transform: 'scale(1)', opacity: 1 }],
      { duration: 300, easing: 'ease-out' }
    );
    return () => anim.cancel();
  }}
>
  

The instance object: instance.old, instance.new, instance.group, instance.imagePair, instance.name.

The types array (second argument) lets you vary animation based on transition type.

---

Animation Timing

---

Troubleshooting

VT not activating: Ensure `` comes before any DOM node. Ensure state update is inside startTransition.

"Two ViewTransition components with the same name": Names must be globally unique. Use IDs: name={hero-${item.id}}.

Back button skips animation: Legacy popstate conflicts with view transitions. Use Navigation API.

flushSync skips animations: Use startTransition instead.

Only updates animate (no enter/exit): Without , React treats swaps as updates. Conditionally render the VT itself, or wrap in .

Competing double animations: Multiple VTs at different tree levels fire simultaneously. Use default="none" on layout-level VTs.

List reorder not animating with useOptimistic: Optimistic values resolve before snapshot. Use committed state for list order.

TS error "Property 'default' is missing": Type-keyed objects require a default key.

Hash fragments cause scroll jumps: Navigate without hash; scroll programmatically after navigation.

Backdrop-blur flickers: Use ::view-transition-old(name) { display: none } + ::view-transition-new(name) { animation: none }.

border-radius lost during transitions: Apply border-radius directly to the captured element.

Skeleton controls slide away: Give matching controls the same viewTransitionName.

Batching: Multiple updates during animation are batched. A→B→C→D becomes B→D.