Forem: Omoshola E.

The Complete Guide to React ViewTransition (Just Released!)

Omoshola E. — Sat, 11 Oct 2025 19:27:24 +0000

🎉 Big news! The React team just released ViewTransition - a game-changing feature for creating smooth, professional animations in React!

Ever noticed how some websites feel buttery smooth when content changes, while others feel jumpy and jarring? The secret is often in the animations. Today, we're diving into React's brand new ViewTransition feature that makes your apps feel premium with surprisingly little code.

What is ViewTransition?

Imagine you're updating content on your website. Normally, old content vanishes and new content appears instantly—like flipping a light switch. ViewTransition is React's way of making those changes smooth and animated instead of jarring and instant.

Think of it like this:

Without ViewTransition: When you update something on the page (like switching between two pieces of content), it just instantly swaps - old content disappears, new content appears.
With ViewTransition: The same update happens, but now it's animated, maybe the old content fades out while the new content fades in, or slides in from the side.

Real-world example:
Imagine you have a tab component. When you click from "Tab A" to "Tab B":

Regular way: Tab A content vanishes, Tab B content appears instantly
With <ViewTransition>: Tab A content smoothly fades/slides out as Tab B content fades/slides in

So is basically saying: "Hey, animate the changes that happen inside me instead of making them instant."

The Basic Rules

For ViewTransition to work, you need three key ingredients:

<ViewTransition> must be the FIRST thing your component returns (before any other DOM elements)
Wrap your content in <ViewTransition>
Update the content inside startTransition()

Rule #1: ViewTransition Must Be First! ⚠️

This is critical: <ViewTransition> must be the very first element your component returns. If there are any other HTML elements before it, animations won't work.

Think of it like a wrapper around your entire component - it needs to be the outermost layer for React to detect when the component appears or disappears.

// ❌ WRONG - <div> comes before ViewTransition
function BadNotification() {
  return (
    <div className="container">
      <h2>Notifications</h2>
      <ViewTransition>
        <div className="notification">
          You have a new message!
        </div>
      </ViewTransition>
    </div>
  );
}

// ❌ WRONG - <Fragment> with <h1> before ViewTransition
function BadProfile() {
  return (
    <>
      <h1>User Profile</h1>
      <ViewTransition>
        <div className="profile-card">
          Profile content...
        </div>
      </ViewTransition>
    </>
  );
}

// ✅ CORRECT - ViewTransition is the FIRST thing returned
function GoodNotification() {
  return (
    <ViewTransition>
      <div className="container">
        <h2>Notifications</h2>
        <div className="notification">
          You have a new message!
        </div>
      </div>
    </ViewTransition>
  );
}

// ✅ CORRECT - ViewTransition wraps everything
function GoodProfile() {
  return (
    <ViewTransition>
      <h1>User Profile</h1>
      <div className="profile-card">
        Profile content...
      </div>
    </ViewTransition>
  );
}

Why this matters: React looks for <ViewTransition> at the component's root to trigger enter/exit animations. If it finds other elements first, it treats your component as a regular update, not an animated transition.

Rule #2: Use startTransition for Updates

Regular setState updates happen instantly. To animate them, wrap the update in startTransition():

// ❌ This won't animate - just regular setState
function Counter() {
  const [count, setCount] = useState(0);

  return (
    <ViewTransition>
      <div>{count}</div>
      <button onClick={() => setCount(count + 1)}>
        Increment
      </button>
    </ViewTransition>
  );
}

// ✅ This will animate - wrapped in startTransition
function Counter() {
  const [count, setCount] = useState(0);

  return (
    <ViewTransition>
      <div>{count}</div>
      <button onClick={() => startTransition(() => setCount(count + 1))}>
        Increment
      </button>
    </ViewTransition>
  );
}

Why? startTransition tells React "this is a non-urgent update that can be animated." Regular setState is considered urgent and happens instantly without animation.

The Four Types of Animations

ViewTransition gives you four moments where animations can happen:

1. 👋 Enter - When Something Appears

This happens when the <ViewTransition> wrapper itself didn't exist before and now it does. If the component get mounted.

function Notification() {
  return (
    <ViewTransition class="fade-in">
      <div className="notification">Message sent!</div>
    </ViewTransition>
  );
}

function App() {
  const [show, setShow] = useState(false);

  const notify = () => {
    startTransition(() => {
      setShow(true);
    });
  };

  return (
    <div>
      <button onClick={notify}>Send</button>
      {show && <Notification />}
    </div>
  );
}

What you see: The notification smoothly fades in when you click "Send."

2. 👋 Exit - When Something Disappears

This happens when the <ViewTransition> wrapper gets removed. If the component unmounts...

function Modal({ onClose }) {
  return (
    <ViewTransition class="fade-out">
      <div className="modal">
        <h2>Modal Content</h2>
        <button onClick={() => startTransition(onClose)}>
          Close
        </button>
      </div>
    </ViewTransition>
  );
}

function App() {
  const [showModal, setShowModal] = useState(false);

  return (
    <div>
      <button onClick={() => startTransition(() => setShowModal(true))}>
        Open Modal
      </button>
      {showModal && <Modal onClose={() => setShowModal(false)} />}
    </div>
  );
}

What you see: The modal smoothly fades out when you click "Close."

3. 🔄 Update - When Something Changes

This happens when content inside the <ViewTransition> changes, or when the wrapper itself moves or resizes.

function Counter() {
  const [count, setCount] = useState(0);

  return (
    <ViewTransition class="pulse">
      <div className="counter">{count}</div>
      <button onClick={() => startTransition(() => setCount(count + 1))}>
        Increment
      </button>
    </ViewTransition>
  );
}

What you see: The number pulses each time it changes.

4. ✨ Share - When Something Morphs Between Locations

This is the coolest one! It happens when you delete (unmount) a named ViewTransition and add (mount) another one with the same name. React treats them as the same element transforming.

function App() {
  const [view, setView] = useState('grid');
  const [selectedId, setSelectedId] = useState(null);

  const selectImage = (id) => {
    startTransition(() => {
      setSelectedId(id);
      setView('detail');
    });
  };

  const goBack = () => {
    startTransition(() => {
      setView('grid');
    });
  };

  if (view === 'grid') {
    return (
      <div className="grid">
        {images.map(img => (
          <ViewTransition key={img.id} name={`image-${img.id}`}>
            <img 
              src={img.thumbnail} 
              onClick={() => selectImage(img.id)}
              className="thumbnail"
            />
          </ViewTransition>
        ))}
      </div>
    );
  }

  return (
    <div>
      <button onClick={goBack}>Back</button>
      <ViewTransition name={`image-${selectedId}`}>
        <img 
          src={images[selectedId].fullSize}
          className="full-size"
        />
      </ViewTransition>
    </div>
  );
}

What you see: Click a thumbnail and it smoothly expands into a full-size image. Click back and it shrinks back to the grid.

The magic: Both ViewTransitions have the same name prop, so React morphs between them instead of fading out and in.

View Transition Class

The View Transition Class, is css class name that React adds to your elements during the animation, so you can style how they animate. It can be a string or an object.
By default, ViewTransition uses a simple crossfade.

Two Ways to Use It

String - One class for everything

<ViewTransition class="my-animation">
  <div>Content</div>
</ViewTransition>

.my-animation {
  animation: slideIn 0.3s ease;
}

@keyframes slideIn {
  from {
    transform: translateX(-100%);
    opacity: 0;
  }
  to {
    transform: translateX(0);
    opacity: 1;
  }
}

What happens: React adds the class my-animation to the element during any animation (enter, exit, update, or share).

Object - Different classes for different animation types

<ViewTransition 
  class={{
    enter: "slide-in",
    exit: "slide-out",
    update: "pulse",
    share: "morph"
  }}
>
  <div>Content</div>
</ViewTransition>

.slide-in {
  animation: slideFromRight 0.3s ease;
}

.slide-out {
  animation: slideToLeft 0.3s ease;
}

.pulse {
  animation: scaleUp 0.2s ease;
}

.morph {
  animation: smoothTransform 0.4s ease;
}

What happens:

When element appears → adds class slide-in
When element disappears → adds class slide-out
When element changes → adds class pulse
When element morphs → adds class morph

Turn Off Specific Animations

<ViewTransition 
  class={{
    enter: "fade-in",
    exit: "none", // No animation when leaving
    update: "pulse"
  }}
>
  <div>Content</div>
</ViewTransition>

🎯 Callbacks: Do Something After Animation

Sometimes you want to run code after an animation finishes:

<ViewTransition 
  onEnter={(element) => {
    console.log("Appeared!");
    element.focus(); // Focus on the new element
  }}
  onExit={(element) => {
    console.log("Disappeared!");
  }}
  onUpdate={(element) => {
    console.log("Changed!");
  }}
>
  <div>Content</div>
</ViewTransition>

Real-world example: Auto-dismiss notifications

<ViewTransition 
  onEnter={(element) => {
    // After the notification fades in, start a timer
    setTimeout(() => {
      startTransition(() => setShow(false));
    }, 3000);
  }}
>
  <div className="notification">Saved successfully!</div>
</ViewTransition>

📋 Animating Lists

The View Transition API provides smooth, animated reordering of lists without manual animation code. When list items change position, the browser automatically creates cross-fade animations that make items appear to glide to their new positions.

This makes list sorting, filtering, and reordering feel much more polished and professional with minimal code!

function TodoList() {
  const [items, setItems] = useState([
    { id: 1, text: 'Buy milk' },
    { id: 2, text: 'Walk dog' },
    { id: 3, text: 'Read book' }
  ]);

  const shuffle = () => {
    startTransition(() => {
      setItems([...items].sort(() => Math.random() - 0.5));
    });
  };

  return (
    <div>
      <button onClick={shuffle}>Shuffle</button>
      {items.map(item => (
        <TodoItem key={item.id} item={item} />
      ))}
    </div>
  );
}

// ✅ ViewTransition at the top - will animate!
function TodoItem({ item }) {
  return (
    <ViewTransition class="reorder">
      <div className="todo-item">
        {item.text}
      </div>
    </ViewTransition>
  );
}

What you see: Click "Shuffle" and items smoothly slide to their new positions.

Important: ViewTransition must be the first thing returned by the list component. This won't work:

// ❌ Won't animate - ViewTransition is wrapped
function TodoItem({ item }) {
  return (
    <div className="todo-item">
      <ViewTransition>
        <span>{item.text}</span>
      </ViewTransition>
    </div>
  );
}

⏳ Working with Suspense

ViewTransition plays nicely with Suspense for loading states. There are two ways to do it:

Method 1: Crossfade (Update Animation)

Wrap the entire Suspense with ViewTransition:

<ViewTransition class="crossfade">
  <Suspense fallback={<LoadingSpinner />}>
    <HeavyContent />
  </Suspense>
</ViewTransition>

What happens:

Shows loading spinner
Content loads
Smoothly crossfades from spinner to content

Visual: Both fade together, blending smoothly.

Method 2: Separate Enter/Exit Animations

Wrap the fallback AND content separately:

<Suspense 
  fallback={
    <ViewTransition class="spinner-exit">
      <LoadingSpinner />
    </ViewTransition>
  }
>
  <ViewTransition class="content-enter">
    <HeavyContent />
  </ViewTransition>
</Suspense>

What happens:

Spinner enters (fades in)
Content loads
Spinner exits (fades out)
Content enters (slides in)

Visual: Distinct stages—spinner leaves, then content arrives.

React Waits for Everything to Be Ready

Before animating, React intelligently waits for:

✅ Data to load
✅ CSS files to load
✅ Fonts to load (up to 500ms)
✅ Images inside ViewTransition to load

Why? To avoid flickering! You don't want to see text appear then suddenly change font, or layout shift when images pop in.

🛣️ Building Routers with ViewTransition

If you're building a router, there are two important things to know:

1. Unblock Navigation in `useLayoutEffect`

React waits for navigation to complete before animating (so scroll position can be restored correctly). Your router must unblock in useLayoutEffect, not useEffect:

// ❌ WRONG - Causes deadlock
function Router() {
  const [blocked, setBlocked] = useState(true);

  useEffect(() => {
    setBlocked(false); // Too late!
  }, []);

  return blocked ? <Loading /> : <Page />;
}

// ✅ CORRECT
function Router() {
  const [blocked, setBlocked] = useState(true);

  useLayoutEffect(() => {
    setBlocked(false); // Just in time!
  }, []);

  return blocked ? <Loading /> : <Page />;
}

Why? useLayoutEffect runs before the browser paints, so React can continue. useEffect runs after, causing a deadlock.

2. Back Button Won't Animate (Yet)

Currently, the browser back button doesn't trigger animations. This is because the old popstate event must be synchronous (to restore scroll/form data immediately), but animations take time.

Solution: Upgrade to the Navigation API (modern browsers):

// Check if supported
if ('navigation' in window) {
  navigation.addEventListener('navigate', (event) => {
    if (event.canIntercept) {
      event.intercept({
        async handler() {
          // Can be async - allows animations!
          await startTransition(() => {
            updateRoute(event.destination.url);
          });
        }
      });
    }
  });
}

With the Navigation API, back button animations work! 🎉

⚠️ Important Rules to always keep in mind when working with `ViewTransition`

1. ViewTransition Must Be First

// ❌ Won't work - there's a div before ViewTransition
function Bad() {
  return (
    <div>
      <h1>Title</h1>
      <ViewTransition>
        <div>Content</div>
      </ViewTransition>
    </div>
  );
}

// ✅ Works - ViewTransition is first
function Good() {
  return (
    <ViewTransition>
      <div>
        <h1>Title</h1>
        <div>Content</div>
      </div>
    </ViewTransition>
  );
}

2. It Animates as a Group, Not Individual Pieces

ViewTransition takes a "snapshot" of everything inside and animates that snapshot. Individual elements don't move separately.

<ViewTransition>
  <div>
    <h1>Title</h1>
    <p>Paragraph 1</p>
    <p>Paragraph 2</p>
  </div>
</ViewTransition>

What happens: Everything moves together as one unit.

If you want individual animations:

<div>
  <ViewTransition><h1>Title</h1></ViewTransition>
  <ViewTransition><p>Paragraph 1</p></ViewTransition>
  <ViewTransition><p>Paragraph 2</p></ViewTransition>
</div>

Now each piece can animate independently!

3. Shared Names Must Be Unique

For "share" animations (morphing), each name must be unique at any given time:

// ❌ BAD - Two elements with same name exist simultaneously
<div>
  <ViewTransition name="avatar">
    <img src="user1.jpg" />
  </ViewTransition>
  <ViewTransition name="avatar">
    <img src="user2.jpg" />
  </ViewTransition>
</div>

// ✅ GOOD - Only one exists at a time
{currentUser === 'user1' && (
  <ViewTransition name="avatar">
    <img src="user1.jpg" />
  </ViewTransition>
)}
{currentUser === 'user2' && (
  <ViewTransition name="avatar">
    <img src="user2.jpg" />
  </ViewTransition>
)}

4. Both Elements Must Be Visible for Share Animation

If you're morphing between two elements (share animation) and one is scrolled off-screen, React won't morph them. Instead, they'll fade out/in separately.

Why? To prevent weird effects where images fly across your entire screen from way down below.

5. ♿ Accessibility: Respect User Preferences

Some users get motion sickness from animations. Always add this CSS:

.my-animation {
  animation: slideIn 0.3s ease;
}

/* Disable for users who prefer reduced motion */
@media (prefers-reduced-motion: reduce) {
  .my-animation {
    animation: none;
  }
}

React doesn't do this automatically—you must add it yourself!

6. 🚫 NEVER Use localStorage or sessionStorage

Critical: Browser storage APIs are not supported in React artifacts and will cause failures.

// ❌ NEVER DO THIS - Will fail!
function BadComponent() {
  const [data, setData] = useState(
    JSON.parse(localStorage.getItem('data'))
  );

  return <ViewTransition>...</ViewTransition>;
}

// ✅ Use React state instead
function GoodComponent() {
  const [data, setData] = useState(initialData);

  return <ViewTransition>...</ViewTransition>;
}

🚀 Real-World Example: Complete App

Let's put it all together with a simple image gallery:

import { useState, startTransition, Suspense } from 'react';

function ImageGallery() {
  const [view, setView] = useState('grid');
  const [selectedId, setSelectedId] = useState(null);

  const images = [
    { id: 1, thumb: 'thumb1.jpg', full: 'full1.jpg', title: 'Sunset' },
    { id: 2, thumb: 'thumb2.jpg', full: 'full2.jpg', title: 'Mountain' },
    { id: 3, thumb: 'thumb3.jpg', full: 'full3.jpg', title: 'Ocean' }
  ];

  const selectImage = (id) => {
    startTransition(() => {
      setSelectedId(id);
      setView('detail');
    });
  };

  const goBack = () => {
    startTransition(() => {
      setView('grid');
    });
  };

  if (view === 'grid') {
    return (
      <div className="grid">
        {images.map(img => (
          <ViewTransition key={img.id} name={`image-${img.id}`}>
            <img 
              src={img.thumb}
              alt={img.title}
              onClick={() => selectImage(img.id)}
              className="thumbnail"
            />
          </ViewTransition>
        ))}
      </div>
    );
  }

  const selected = images.find(img => img.id === selectedId);

  return (
    <div className="detail-view">
      <button onClick={goBack}>← Back</button>

      <Suspense 
        fallback={
          <ViewTransition class="skeleton-animation">
            <div className="skeleton" />
          </ViewTransition>
        }
      >
        <ViewTransition name={`image-${selectedId}`}>
          <img 
            src={selected.full}
            alt={selected.title}
            className="full-image"
          />
        </ViewTransition>
      </Suspense>

      <h2>{selected.title}</h2>
    </div>
  );
}

CSS:

.grid {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 1rem;
}

.thumbnail {
  width: 100%;
  cursor: pointer;
  border-radius: 8px;
  transition: transform 0.2s;
}

.thumbnail:hover {
  transform: scale(1.05);
}

.detail-view {
  max-width: 800px;
  margin: 0 auto;
}

.full-image {
  width: 100%;
  border-radius: 12px;
}

.skeleton {
  width: 100%;
  height: 500px;
  background: linear-gradient(
    90deg,
    #f0f0f0 25%,
    #e0e0e0 50%,
    #f0f0f0 75%
  );
  background-size: 200% 100%;
  animation: shimmer 1.5s infinite;
  border-radius: 12px;
}

@keyframes shimmer {
  0% {
    background-position: 200% 0;
  }
  100% {
    background-position: -200% 0;
  }
}

/* Respect user preferences */
@media (prefers-reduced-motion: reduce) {
  .thumbnail {
    transition: none;
  }

  .skeleton {
    animation: none;
  }
}

What this app does:

Shows a grid of thumbnail images
Click a thumbnail → It smoothly expands to full size (share animation)
Shows a skeleton loader while the full image loads (suspense)
Click back → Image smoothly shrinks back to grid position

📝 Key Takeaways

Always wrap updates in startTransition() - Regular setState won't animate
Put <ViewTransition> first - It must be the first thing your component returns
Use name prop for morphing - Same name = elements morph between positions
Customize with class prop - Different animations for enter/exit/update/share
Respect accessibility - Add prefers-reduced-motion media queries
Works with Suspense - Two methods: crossfade or separate enter/exit
Never use browser storage - Use React state instead
Router builders - Use useLayoutEffect and Navigation API for best results

🌐 Browser Support

ViewTransition currently works in:

✅ Modern browsers with View Transitions API support
✅ Web applications (React DOM)
❌ React Native (coming in the future)

🎬 Conclusion

ViewTransition is React's brand new powerful tool for creating smooth, professional animations with minimal code. Now that it's officially released, you can start using it in your projects today!

Instead of managing complex animation libraries, you simply:

Wrap content in <ViewTransition>
Update inside startTransition()
Style with CSS

That's it! React handles the rest—snapshots, timing, coordination, and cleanup.

Start with simple enter/exit animations, then level up to shared element transitions for that premium app feel. Your users will love the polish! ✨

This is a brand new feature - what animations are you excited to build with ViewTransition? Drop a comment below! 👇

If you found this helpful, give it a ❤️ and share with your fellow developers!

Happy coding! 🚀

# 🚀 Next.js 15: The searchParams Breaking Change You Need to Know About

Omoshola E. — Mon, 01 Sep 2025 17:38:35 +0000

Understanding the shift from synchronous objects to Promises and how to migrate your code

Released on October 21st, 2024, Next.js 15 introduced several exciting features, but one change caught many developers off guard: searchParams is now a Promise. If you've been working with Next.js 14 and are planning to upgrade, this breaking change will require some attention. Let's dive deep into what changed, why it changed, and how to handle it properly.

📋 Table of Contents

What Changed?
Why This Change Was Made
Before vs After: Code Examples
Migration Guide
Common Pitfalls
Best Practices
Real-World Example
Conclusion

What Changed?

In Next.js 14, searchParams was a simple object that you could access synchronously:

// ✅ Next.js 14 - Synchronous access
export default function SearchPage({ searchParams }) {
  const query = searchParams.q;
  const filter = searchParams.filter;

  return (
    <div>
      <h1>Search Results for: {query}</h1>
      <p>Filter: {filter}</p>
    </div>
  );
}

In Next.js 15, searchParams becomes a Promise that must be awaited:

// ✅ Next.js 15 - Asynchronous access
export default async function SearchPage({ searchParams }) {
  const resolvedParams = await searchParams;
  const query = resolvedParams.q;
  const filter = resolvedParams.filter;

  return (
    <div>
      <h1>Search Results for: {query}</h1>
      <p>Filter: {filter}</p>
    </div>
  );
}

Why This Change Was Made

This change isn't arbitrary—it's part of Next.js's broader strategy to improve performance and enable better streaming capabilities:

🎯 1. Streaming & Concurrent Rendering

By making searchParams async, Next.js can start rendering parts of your page before all search parameters are resolved, leading to faster perceived load times.

🎯 2. Better Resource Management

Async searchParams allows Next.js to handle URL parsing more efficiently, especially for complex query strings.

🎯 3. Consistency with React's Direction

This aligns with React's push toward async components and Suspense boundaries.

🎯 4. Future-Proofing

Sets the foundation for more advanced server-side optimizations in future releases.

Before vs After: Code Examples

Let's look at some practical examples to see the difference:

Simple Search Page

Next.js 14:

// app/search/page.js
export default function SearchPage({ searchParams }) {
  const { q, category, sort } = searchParams;

  return (
    <div className="container mx-auto p-4">
      <h1>Search Results</h1>
      {q && <p>Searching for: "{q}"</p>}
      {category && <p>Category: {category}</p>}
      {sort && <p>Sort by: {sort}</p>}
    </div>
  );
}

Next.js 15:

// app/search/page.js
export default async function SearchPage({ searchParams }) {
  const { q, category, sort } = await searchParams;

  return (
    <div className="container mx-auto p-4">
      <h1>Search Results</h1>
      {q && <p>Searching for: "{q}"</p>}
      {category && <p>Category: {category}</p>}
      {sort && <p>Sort by: {sort}</p>}
    </div>
  );
}

E-commerce Product Listing

Next.js 14:

// app/products/page.js
export default function ProductsPage({ searchParams }) {
  const page = parseInt(searchParams.page) || 1;
  const limit = parseInt(searchParams.limit) || 12;
  const sortBy = searchParams.sort || 'name';
  const filters = {
    brand: searchParams.brand,
    minPrice: searchParams.min_price,
    maxPrice: searchParams.max_price,
  };

  return (
    <div>
      <ProductList 
        page={page}
        limit={limit}
        sortBy={sortBy}
        filters={filters}
      />
    </div>
  );
}

Next.js 15:

// app/products/page.js
export default async function ProductsPage({ searchParams }) {
  const params = await searchParams;
  const page = parseInt(params.page) || 1;
  const limit = parseInt(params.limit) || 12;
  const sortBy = params.sort || 'name';
  const filters = {
    brand: params.brand,
    minPrice: params.min_price,
    maxPrice: params.max_price,
  };

  return (
    <div>
      <ProductList 
        page={page}
        limit={limit}
        sortBy={sortBy}
        filters={filters}
      />
    </div>
  );
}

Migration Guide

Step 1: Make Your Page Component Async

// Before
export default function MyPage({ searchParams }) {
  // ...
}

// After
export default async function MyPage({ searchParams }) {
  // ...
}

Step 2: Await searchParams

// Before
const { param1, param2 } = searchParams;

// After
const { param1, param2 } = await searchParams;

Step 3: Update Any Helper Functions

If you have utility functions that process searchParams, they might need updates too:

// Before
function buildFilterObject(searchParams) {
  return {
    category: searchParams.category,
    priceRange: searchParams.price_range,
    inStock: searchParams.in_stock === 'true'
  };
}

// After
async function buildFilterObject(searchParams) {
  const params = await searchParams;
  return {
    category: params.category,
    priceRange: params.price_range,
    inStock: params.in_stock === 'true'
  };
}

Common Pitfalls

❌ Pitfall 1: Forgetting to Await

// This will break in Next.js 15
export default async function Page({ searchParams }) {
  const query = searchParams.q; // Error: searchParams is a Promise
  return <div>{query}</div>;
}

❌ Pitfall 2: Not Making Component Async

// This won't work
export default function Page({ searchParams }) {
  const params = await searchParams; // Error: await in non-async function
  return <div>...</div>;
}

❌ Pitfall 3: Multiple Awaits

// Inefficient - awaiting multiple times
export default async function Page({ searchParams }) {
  const query = (await searchParams).q;
  const filter = (await searchParams).filter;
  const page = (await searchParams).page;
  // ...
}

// ✅ Better - await once, destructure
export default async function Page({ searchParams }) {
  const { q: query, filter, page } = await searchParams;
  // ...
}

Best Practices

1. Destructure After Awaiting

export default async function Page({ searchParams }) {
  // ✅ Clean and efficient
  const { q, category, sort, page } = await searchParams;

  return (
    <div>
      <SearchResults 
        query={q}
        category={category}
        sortBy={sort}
        currentPage={parseInt(page) || 1}
      />
    </div>
  );
}

2. Handle URL Parameter Validation

export default async function Page({ searchParams }) {
  const params = await searchParams;

  // Validate and provide defaults
  const page = Math.max(1, parseInt(params.page) || 1);
  const limit = Math.min(100, Math.max(1, parseInt(params.limit) || 10));
  const sortBy = ['name', 'price', 'date'].includes(params.sort) 
    ? params.sort 
    : 'name';

  return <ProductGrid page={page} limit={limit} sortBy={sortBy} />;
}

3. Create Reusable Parameter Parsers

// lib/params.js
export async function parseSearchParams(searchParams) {
  const params = await searchParams;

  return {
    query: params.q || '',
    page: Math.max(1, parseInt(params.page) || 1),
    limit: Math.min(50, Math.max(1, parseInt(params.limit) || 10)),
    filters: {
      category: params.category,
      priceMin: parseFloat(params.price_min) || 0,
      priceMax: parseFloat(params.price_max) || Infinity,
      inStock: params.in_stock === 'true'
    }
  };
}

// app/products/page.js
import { parseSearchParams } from '@/lib/params';

export default async function ProductsPage({ searchParams }) {
  const { query, page, limit, filters } = await parseSearchParams(searchParams);

  return <ProductList {...{ query, page, limit, filters }} />;
}

Real-World Example

Let's build a complete search page that demonstrates the new async pattern:

// app/blog/page.js
import { BlogCard } from '@/components/BlogCard';
import { Pagination } from '@/components/Pagination';

export default async function BlogPage({ searchParams }) {
  // Await and destructure searchParams
  const {
    q: query,
    category,
    tag,
    page: pageParam,
    sort
  } = await searchParams;

  // Process parameters with validation
  const currentPage = Math.max(1, parseInt(pageParam) || 1);
  const postsPerPage = 10;
  const sortBy = ['date', 'title', 'views'].includes(sort) ? sort : 'date';

  // Build filter object
  const filters = {
    ...(query && { search: query }),
    ...(category && { category }),
    ...(tag && { tag }),
  };

  // Simulate API call (replace with your actual data fetching)
  const { posts, totalCount } = await fetchBlogPosts({
    filters,
    page: currentPage,
    limit: postsPerPage,
    sortBy
  });

  const totalPages = Math.ceil(totalCount / postsPerPage);

  return (
    <div className="container mx-auto px-4 py-8">
      <div className="mb-8">
        <h1 className="text-4xl font-bold mb-4">Blog Posts</h1>

        {/* Display active filters */}
        {query && (
          <div className="mb-4">
            <span className="text-gray-600">Searching for: </span>
            <span className="font-semibold">"{query}"</span>
          </div>
        )}

        {(category || tag) && (
          <div className="flex gap-2 mb-4">
            {category && (
              <span className="bg-blue-100 text-blue-800 px-3 py-1 rounded-full text-sm">
                Category: {category}
              </span>
            )}
            {tag && (
              <span className="bg-green-100 text-green-800 px-3 py-1 rounded-full text-sm">
                Tag: {tag}
              </span>
            )}
          </div>
        )}
      </div>

      {/* Blog posts grid */}
      <div className="grid md:grid-cols-2 lg:grid-cols-3 gap-6 mb-8">
        {posts.map(post => (
          <BlogCard key={post.id} post={post} />
        ))}
      </div>

      {/* Pagination */}
      {totalPages > 1 && (
        <Pagination 
          currentPage={currentPage}
          totalPages={totalPages}
          baseUrl="/blog"
          searchParams={filters}
        />
      )}
    </div>
  );
}

// Simulated data fetching function
async function fetchBlogPosts({ filters, page, limit, sortBy }) {
  // This would be your actual API call or database query
  // For demo purposes, we'll simulate it
  await new Promise(resolve => setTimeout(resolve, 100));

  return {
    posts: Array.from({ length: limit }, (_, i) => ({
      id: (page - 1) * limit + i + 1,
      title: "`Blog Post ${(page - 1) * limit + i + 1}`,"
      excerpt: "This is a sample blog post excerpt...",
      category: filters.category || 'General',
      publishedAt: new Date().toISOString(),
    })),
    totalCount: 95 // Simulated total
  };
}

Performance Benefits

The async nature of searchParams enables several performance optimizations:

Streaming Benefits

export default async function Page({ searchParams }) {
  // This can start rendering immediately
  return (
    <div>
      <Header />
      <Suspense fallback={<SearchSkeleton />}>
        <SearchResults searchParams={searchParams} />
      </Suspense>
      <Footer />
    </div>
  );
}

async function SearchResults({ searchParams }) {
  const { q } = await searchParams; // Only this component waits
  const results = await fetchSearchResults(q);

  return <ResultsList results={results} />;
}

Concurrent Data Fetching

export default async function Page({ searchParams, params }) {
  // Both can be resolved concurrently
  const [resolvedSearchParams, resolvedParams] = await Promise.all([
    searchParams,
    params
  ]);

  const { q } = resolvedSearchParams;
  const { slug } = resolvedParams;

  // Fetch data concurrently
  const [searchResults, pageData] = await Promise.all([
    fetchSearchResults(q),
    fetchPageData(slug)
  ]);

  return <CombinedView searchResults={searchResults} pageData={pageData} />;
}

TypeScript Support

For TypeScript users, here's how to properly type your async page components:

// types/page.ts
export interface SearchParams {
  q?: string;
  category?: string;
  page?: string;
  sort?: 'date' | 'title' | 'views';
  [key: string]: string | string[] | undefined;
}

// app/search/page.tsx
interface PageProps {
  searchParams: Promise<SearchParams>;
}

export default async function SearchPage({ searchParams }: PageProps) {
  const { q, category, page, sort } = await searchParams;

  // Type-safe parameter processing
  const currentPage = page ? Math.max(1, parseInt(page)) : 1;
  const sortBy: 'date' | 'title' | 'views' = 
    sort && ['date', 'title', 'views'].includes(sort) ? sort : 'date';

  return (
    <div>
      <SearchResults 
        query={q}
        category={category}
        page={currentPage}
        sortBy={sortBy}
      />
    </div>
  );
}

Automated Migration

You can use a simple find-and-replace approach for basic migrations:

Find Pattern:

export default function.*\({ searchParams }\)

Replace With:

export default async function $1({ searchParams }) {
  const resolvedSearchParams = await searchParams;

Then update all references to searchParams to use resolvedSearchParams.

Testing Your Migration

Here's how to test that your migration works correctly:

// __tests__/search-page.test.js
import { render } from '@testing-library/react';
import SearchPage from '@/app/search/page';

// Mock searchParams as a resolved Promise
const mockSearchParams = Promise.resolve({
  q: 'test query',
  category: 'tech',
  page: '2'
});

test('renders search page with params', async () => {
  const { getByText } = render(
    await SearchPage({ searchParams: mockSearchParams })
  );

  expect(getByText('Searching for: "test query"')).toBeInTheDocument();
  expect(getByText('Category: tech')).toBeInTheDocument();
});

Error Handling

Always implement proper error handling when working with async searchParams:

export default async function Page({ searchParams }) {
  try {
    const params = await searchParams;
    const { q, filter } = params;

    return <SearchResults query={q} filter={filter} />;
  } catch (error) {
    console.error('Failed to resolve searchParams:', error);

    return (
      <div className="error-state">
        <h2>Something went wrong</h2>
        <p>Unable to load search parameters</p>
      </div>
    );
  }
}

Quick Migration Checklist

[ ] Make page component async (async function)
[ ] Await searchParams before accessing properties
[ ] Update destructuring to happen after await
[ ] Test with different URL patterns
[ ] Update TypeScript types if using TypeScript
[ ] Update any utility functions that process searchParams
[ ] Add error handling for Promise rejection cases
[ ] Update tests to handle async components

Conclusion

The transition from synchronous to asynchronous searchParams in Next.js 15 represents a significant step forward in web performance optimization. While it requires some code changes, the benefits in terms of streaming, concurrent rendering, and overall performance make it worthwhile.

The migration is straightforward: make your components async, await searchParams, and you're good to go. The real benefits come from understanding how this change enables better user experiences through faster page loads and more responsive applications.

Key Takeaways:

🔄 searchParams is now a Promise in Next.js 15
⚡ This enables better streaming and performance
🛠️ Migration is simple: add async and await
🎯 Focus on the performance benefits this unlocks
🔍 Always validate and sanitize URL parameters

Have you started migrating to Next.js 15 yet? What other changes have you encountered? Share your experiences in the comments below!

Want to stay updated on Next.js developments? Follow me for more web development insights and tutorials!

Resources

#nextjs #react #webdev #javascript #frontend #migration