Comprehensive Guide to Accessing Query Parameters in Next.js

In Next.js development, handling URL query parameters is essential for dynamic page content. Many developers face challenges when passing parameters, such as navigating from a home page to an about page with a name parameter. Based on common issues and official documentation, this article systematically introduces multiple methods for extracting query parameters, ensuring modern and efficient code practices.

Using the useRouter Hook

The useRouter hook is a recommended approach in Next.js, suitable for functional components, allowing easy access to query parameters via the router object. This method relies on client-side routing and should be used in client components. For example, in an about page, parameters can be retrieved through router.query.

import { useRouter } from 'next/router';

export default function About() {
  const router = useRouter();
  const { name } = router.query;

  return 
Welcome, {name}!
;
}

In this code, the router.query object automatically parses the query string from the URL, such as when accessing /about?name=leangchhean, the name variable will contain 'leangchhean'. Note that query parameters might be undefined during initial render, so it's advisable to handle default values.

Using the getInitialProps Method

For class components or scenarios requiring server-side rendering, getInitialProps allows fetching query parameters during the initial page load. This method is called in the component lifecycle, and the returned object is passed as props to the component.

import React from 'react';

class About extends React.Component {
  static getInitialProps({ query }) {
    return { query };
  }

  render() {
    const { name } = this.props.query;
    return 
Welcome, {name}!
;
  }
}

export default About;

For stateless functional components, getInitialProps can also be defined. However, with updates in Next.js versions, this method is gradually being replaced by hooks, and it's recommended to use more modern approaches in new projects.

Next.js 13: searchParams Prop and useSearchParams Hook

Next.js 13 introduces the App Router, providing new ways to handle parameters. Page components (Server Components) receive a searchParams prop, while Client Components can use the useSearchParams hook. This approach optimizes partial rendering and dynamic routing.

// Server Component example
export default function About({ searchParams }) {
  const name = searchParams.name || 'default';
  return 
Welcome, {name}!
;
}

// Client Component example
'use client';
import { useSearchParams } from 'next/navigation';

export default function About() {
  const searchParams = useSearchParams();
  const name = searchParams.get('name') || 'default';

  return 
Welcome, {name}!
;
}

The useSearchParams hook returns a read-only URLSearchParams object, supporting methods like get() to retrieve parameter values. For static rendering, it's recommended to wrap Client Components using useSearchParams in a Suspense boundary to avoid build errors.

Best Practices and Version Compatibility

When selecting a method, consider the Next.js version and component type. useRouter and useSearchParams are ideal for client-side interactions, while getInitialProps and the searchParams prop are better for server-side scenarios. Historical methods like the url prop have been deprecated since version 6 and should be avoided. Always refer to official documentation for updates to ensure code compatibility and performance.