Navigating Next.js Query Params: A Comprehensive Guide

Query parameters are an essential part of the web. They are used to pass state information between client components and server components. Whether you're building a dashboard with filters or a search page that retains user input across navigations, query parameters are the key to preserving and transmitting this data.

What Are Query Parameters?

Query parameters, also known as URL parameters or search parameters, are a set of key-value pairs appended to the URL string. They start after the question mark (?) and are separated by the ampersand (&) when there are multiple parameters. Each key-value pair is a query parameter that allows you to pass data to the server components or manipulate the content on the client side without the need for a page reload.

Utilizing Query Parameters in URLs

In the context of a URL, query parameters are used to sort, filter, or search data on a page. They are a part of the URL string that comes after the pathname and can be used to pass additional information to the page components. This is particularly useful when you need to retrieve or display data based on user input or when you want to create dynamic routes that respond to changes in the query string.

Query Parameters in Action

Let's look at an example of a URL with query parameters:

Copy
1
https://www.example.com/products?category=shoes&color=black

In this URL, category and color are the keys, while shoes and black are their respective values. These query parameters can be used by server components to fetch data that matches the specified category and color, or by client components to highlight the active filters on the current page.

Here's a simple code snippet showing how you might access these parameters within a Next.js page component:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import { useRouter } from 'next/router';

const ProductsPage = () => {
  const router = useRouter();
  const { category, color } = router.query;

  console.log('Selected category:', category);
  console.log('Selected color:', color);

  // Fetch data based on query parameters
  // ...

  return (
    <div>
      <h2>Filtered Products</h2>
      {/* Render products based on the query parameters */}
    </div>
  );
};

In this example, we use the useRouter hook from Next.js to access the router object, which contains the query object. The query object holds the query parameters from the current URL, allowing us to log their values and potentially use them to fetch data or render specific components on the page.

Accessing Query Parameters in Next.js

Next.js Pages and Routing

Next.js offers a file-system-based routing mechanism, where files and folders in the pages directory automatically become routes in your application. This approach simplifies the creation of new pages and dynamic routes. When it comes to handling query parameters, Next.js provides built-in hooks and functions that make accessing these parameters straightforward, whether you're on the client side or the server side.

Using the useRouter Hook

The useRouter hook is part of the Next.js router and is a client-side hook that allows you to access the router object within your page components. This router object contains the query object, which holds the query parameters of the current URL.

Here's a code snippet demonstrating how to use the useRouter hook to access query parameters:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import { useRouter } from 'next/router';

const MyPage = () => {
  const router = useRouter();
  const { query } = router;

  console.log('Query parameters:', query);

  return (
    <div>
      <h2>Accessing Query Parameters</h2>
      {/* Render content based on query parameters */}
    </div>
  );
};

export default MyPage;

In this example, we import the useRouter hook from the Next.js router library and use it to retrieve the router object. We then destructure the query object from router to access the query parameters.

Server-Side Rendering with getServerSideProps

When you need to fetch data based on query parameters during server-side rendering, you can use the getServerSideProps function. This function runs on the server for each request and receives the context object, which includes the query object.

Here's how you can access query parameters in getServerSideProps:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
export async function getServerSideProps(context) {
  const { query } = context;

  console.log('Server-side query parameters:', query);

  // Fetch data based on query parameters
  // ...

  return {
    props: {}, // Pass data to the page as props
  };
}

In this code snippet, getServerSideProps is an async function that receives the context parameter. The query object is extracted from context, allowing you to log the query parameters and fetch data accordingly.

Static Generation with getStaticProps and getStaticPaths

For static generation, Next.js provides getStaticProps and getStaticPaths. While getStaticProps is used to fetch data at build time, getStaticPaths is used to specify dynamic routes that should be pre-rendered.

Here's an example of accessing query parameters with getStaticPaths:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
export async function getStaticPaths() {
  // Define paths with query parameters that should be statically generated
  return {
    paths: [
      { params: { category: 'shoes' } },
      { params: { category: 'accessories' } },
      // More paths...
    ],
    fallback: false,
  };
}

export async function getStaticProps({ params }) {
  console.log('Static generation query parameters:', params);

  // Fetch data based on query parameters
  // ...

  return {
    props: {}, // Pass data to the page as props
  };
}

In getStaticPaths, we define the paths that include the query parameters we want to pre-render. In getStaticProps, we access these parameters through the params object provided by the context.

Dynamic Routing with Query Params

Dynamic Routes in Next.js

Dynamic routes in Next.js allow you to create pages that can match a variety of URL structures. These routes are defined by placing square brackets around a file or folder name within the ‘pages' directory. For example, a file named [id].js would match any route like /posts/1 or /posts/abc. This flexibility is particularly useful when you want to create pages that adapt to different content based on the URL parameters provided.

Creating Dynamic Pages with Query Parameters

To create a dynamic page that responds to query parameters, you first define the dynamic route using the file naming convention mentioned above. Then, within the page component, you can access the dynamic segments of the URL as query parameters using the useRouter hook or the context object provided to getServerSideProps or getStaticProps.

Here's an example of how to create a dynamic route that responds to query parameters:

1. Create a file in the ‘pages’ directory that corresponds to the dynamic segment of the URL, for example, [category].js.

2. Within this file, use the useRouter hook to access the dynamic segment and any additional query parameters.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// pages/[category].js
import { useRouter } from 'next/router';

const CategoryPage = () => {
  const router = useRouter();
  const { category } = router.query; // Access the dynamic segment
  const { filter } = router.query; // Access an additional query parameter

  console.log('Category:', category);
  console.log('Filter:', filter);

  // Fetch data based on the category and filter query parameters
  // ...

  return (
    <div>
      <h2>Products in {category}</h2>
      {/* Render products based on the category and filter */}
    </div>
  );
};

export default CategoryPage;

In this example, the file [category].js will match routes like /shoes or /accessories, and the dynamic segment will be available as a query parameter under the key category. If the URL includes additional query parameters, such as /shoes?filter=on-sale, the filter parameter can also be accessed from the query object.

Example of a Dynamic Route with Query Parameters

Let's consider a more concrete example. Suppose you have an e-commerce application where you want to display products based on their category and optional filters like price range or brand. You could create a dynamic route to handle this:

1. Create a file named [category].js in the ‘pages’ directory.

2. Use the useRouter hook to access the category and any additional query parameters.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// pages/[category].js
import { useRouter } from 'next/router';

const ProductsByCategory = () => {
  const router = useRouter();
  const { category, price, brand } = router.query;

  console.log(`Displaying products in category: ${category} with price: ${price} and brand: ${brand}`);

  // Fetch and display products based on the category, price, and brand
  // ...

  return (
    <div>
      <h2>Products in {category}</h2>
      {/* Render products based on the category and additional filters */}
    </div>
  );
};

export default ProductsByCategory;

With this setup, a URL like /shoes?price=under-100&brand=nike would render the ProductsByCategory component, and within that component, you could fetch and display products that are shoes under $100 from Nike.

Manipulating Query Parameters in Next.js

Programmatically Navigating with Query Parameters

In Next.js, you can programmatically navigate between pages and manipulate query parameters using the Next router methods router.push and router.replace. These methods allow you to update the URL and navigate to a new page without a full page refresh, providing a smoother user experience.

Using ‘router.push’

The router.push method is used to navigate to a new page and add a new entry to the browser's history stack. This means that when the user clicks the back button, they will return to the previous page.

Here's a code snippet demonstrating how to use router.push to navigate with query parameters:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { useRouter } from 'next/router';

const MyComponent = () => {
  const router = useRouter();

  const handleSearch = (searchTerm) => {
    // Navigate to the same page with a new query parameter for the search term
    router.push({
      pathname: router.pathname,
      query: { ...router.query, search: searchTerm },
    });
  };

  return (
    <div>
      <input type="text" placeholder="Search..." onChange={(e) => handleSearch(e.target.value)} />
      {/* Other content */}
    </div>
  );
};

export default MyComponent;

In this example, when the user types into the search input, the handleSearch function is called, which uses router.push to update the current URL with the new search term while preserving other existing query parameters.

Using router.replace

The router.replace method is similar to router.push, but it replaces the current entry in the history stack instead of adding a new one. This is useful when you want to navigate to a new page but don't want the user to be able to go back to the previous state.

Here's how you can use router.replace:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import { useRouter } from 'next/router';

const MyComponent = () => {
  const router = useRouter();

  const handleFilterChange = (filter) => {
    // Replace the current URL with a new query parameter for the filter
    router.replace({
      pathname: router.pathname,
      query: { ...router.query, filter },
    });
  };

  return (
    <div>
      <select onChange={(e) => handleFilterChange(e.target.value)}>
        <option value="all">All</option>
        <option value="available">Available</option>
        <option value="sold-out">Sold Out</option>
      </select>
      {/* Other content */}
    </div>
  );
};

export default MyComponent;

In this example, when the user selects a filter option, the handleFilterChange function updates the URL with the selected filter without adding a new history entry.

Preserving Query Parameters During Navigation

When navigating between pages, you may want to preserve certain query parameters to maintain the application's state across page transitions. There are several strategies to achieve this:

1. Passing Query Parameters Manually: When using router.push or router.replace, you can manually include the query parameters you want to preserve in the new URL.

2. Using a Global State Management Library: Libraries like Redux or Zustand can help manage the application state globally, including the state represented by query parameters.

3. Storing in Local Storage or Session Storage: For more persistent state management across page reloads, you can store query parameters in local storage or session storage and retrieve them when needed.

4. Custom Hooks: Creating custom hooks to manage query parameters can abstract the logic of preserving parameters during navigation, making your components cleaner and more reusable.

Conclusion

In conclusion, query parameters are a fundamental feature in Next.js that enable dynamic and stateful web applications. We've covered how to access, manipulate, and maintain query parameters, ensuring seamless navigation and data retrieval. With the useRouter hook, dynamic routing, and methods like router.push and router.replace, you have the tools to craft interactive user experiences. Keep these insights in mind as you develop with Next.js, and you'll be well on your way to creating more engaging and personalized web applications.