Introduce a searchParams() function for Server Components to avoid prop drilling

[Tobi-mmt]

Goals

1. Eliminate prop drilling for searchParams through multiple layers of nested Server Components.
2. Improve component encapsulation and reusability by allowing components to access searchParams directly, without their parents needing to be aware of this dependency.
3. Create API consistency by providing a server-side searchParams() function that mirrors the convenience of existing functions like headers() and cookies().

Non-Goals

1. This proposal does not aim to change or replace the existing useSearchParams hook for Client Components.
2. It does not propose a method for modifying search parameters on the server, only for reading them.
3. It does not aim to bypass the intended behavior of dynamic rendering. Accessing searchParams via this method would rightly opt the page into server-side dynamic rendering, consistent with headers() and cookies().

Background

In the current version of the App Router, the only way for a Server Component to access URL search parameters is to receive them as props passed down from a root component like page.tsx. This is the only alternative.

This requirement leads to a common and cumbersome pattern known as "prop drilling." If a deeply nested component (e.g., a <Pagination /> component) needs the page parameter, every single component in its parent hierarchy must accept searchParams as a prop and forward it.

Example of the current alternative (prop drilling):

// page.tsx -> ProductPage.tsx -> CardGrid.tsx -> Pagination.tsx
export default function Page({ searchParams }) {
  // Must pass it down...
  return <ProductPage searchParams={searchParams} />;
}

// ...which passes it to CardGrid, which finally passes it to...

export default function Pagination({ searchParams }) {
  // ...where it's finally used.
  const currentPage = searchParams?.page || '1';
  return <div>Current Page: {currentPage}</div>;
}

This pattern creates unnecessary boilerplate and tightly couples components.

The need for this feature is highlighted by the existence of prior art within Next.js itself: the headers() and cookies() functions from next/headers. These functions set a clear precedent for providing convenient, direct access to request-specific data in any Server Component without prop drilling. This proposal aims to extend that same ergonomic developer experience to searchParams.

A similar issue was already mentioned for params in another discussion here #45543

Proposal

This feature should be implemented as a new function, searchParams(), exported from next/navigation.

When called within a Server Component, it would return a read-only instance of URLSearchParams, allowing developers to easily access the query string parameters of the current request.

Proposed Implementation:

A new function would be exposed, allowing any Server Component to be refactored like this:

// app/components/Pagination.tsx

// Proposed API, consistent with other hooks/utilities
import { searchParams } from 'next/navigation'; 

export default async function Pagination() {
  const params = await searchParams();
  const currentPage = params.get('page') || '1';
  
  return <div>Current Page: {currentPage}</div>;
}

This implementation would make the component self-contained and remove the need for any parent component to know about or pass down searchParams.

I believe this is a crucial quality-of-life improvement for the framework.

[samselikoff]

The reason this doesn't exist is because if you used inside of a layout, then you'd need to refetch the layout upon every navigation.

cookies() and headers() exist because they're assumed to be static. They're stashed as if you read client cached data. And we know if cookies change because of cookies().set(...). So neither are refetched on every navigation, but searchParams would have to be, which would cause layouts to re-render too frequently.

[Tobi-mmt]

Thank you for the explanation! That makes perfect sense.

I completely agree that forcing layouts to re-render due to searchParams changes would undermine one of the core benefits of the App Router, and the distinction you made between the highly dynamic nature of searchParams versus the semi-static nature of cookies and headers clarifies the trade-off very nice.

Given this, what are your thoughts on a more scoped version of this proposal?

Could a searchParams() function be introduced that is explicitly disallowed or throws an error if used within a layout.tsx file, but is available for use within a page.tsx component and its children?

The primary pain point of prop drilling exists within the page's component tree, not typically in the shared layout. A page and its children are expected to re-render when search parameters change.

This approach would:

1. Solve the prop-drilling problem for page-specific components.
2. Preserve the crucial performance and state-persistence benefits of stable layouts.

This seems like a way to get the ergonomic benefits where they are most needed, without compromising the architectural integrity of layouts.

What do you think about that?