Learning Objectives

Dynamic routes and route parameters
Route groups and organization
Navigation with Link and useRouter
Active link states
Redirects and rewrites

1. Dynamic Routes

Dynamic routes allow you to create pages that respond to URL parameters. This is essential for pages like user profiles, product details, or transaction records where the content varies based on an identifier.

Single Parameter

Square brackets in the folder name indicate a dynamic segment. The value from the URL is accessible via the params prop. In Next.js 16, params is a Promise that must be awaited.

// app/transactions/[id]/page.tsx
// Matches: /transactions/123, /transactions/abc

type Props = {
  params: Promise<{ id: string }>;
};

export default async function TransactionPage({ params }: Props) {
  const { id } = await params;

  return <div>Transaction ID: {id}</div>;
}

Multiple Parameters

Routes can have multiple dynamic segments. Each bracket pair creates a parameter that you can access in your component.

// app/services/[category]/[productId]/page.tsx
// Matches: /services/airtime/mtn-100

type Props = {
  params: Promise<{ category: string; productId: string }>;
};

export default async function ProductPage({ params }: Props) {
  const { category, productId } = await params;

  return (
    <div>
      <p>Category: {category}</p>
      <p>Product: {productId}</p>
    </div>
  );
}

Catch-All Routes

Catch-all routes use the spread syntax to match any number of path segments. The slug parameter becomes an array of strings representing each segment.

// app/docs/[...slug]/page.tsx
// Matches: /docs/a, /docs/a/b, /docs/a/b/c

type Props = {
  params: Promise<{ slug: string[] }>;
};

export default async function DocsPage({ params }: Props) {
  const { slug } = await params;
  // /docs/getting-started/installation -> ['getting-started', 'installation']

  return <div>Docs: {slug.join(" / ")}</div>;
}

Optional Catch-All

Double brackets make the catch-all route optional, meaning it also matches the parent route without any segments.

// app/shop/[[...categories]]/page.tsx
// Matches: /shop, /shop/electronics, /shop/electronics/phones

type Props = {
  params: Promise<{ categories?: string[] }>;
};

export default async function ShopPage({ params }: Props) {
  const { categories } = await params;

  if (!categories) {
    return <div>All Products</div>;
  }

  return <div>Categories: {categories.join(" > ")}</div>;
}

2. Route Groups

Route groups organize routes without affecting the URL structure. By wrapping folder names in parentheses, you can create logical groupings that share layouts or configurations without adding to the URL path.

app/
├── (marketing)/           # Group for marketing pages
│   ├── layout.tsx         # Marketing layout
│   ├── page.tsx           # / (home)
│   ├── about/page.tsx     # /about
│   └── pricing/page.tsx   # /pricing
│
├── (auth)/                # Group for auth pages
│   ├── layout.tsx         # Auth layout (centered, minimal)
│   ├── login/page.tsx     # /login
│   └── register/page.tsx  # /register
│
└── (dashboard)/           # Group for dashboard
    ├── layout.tsx         # Dashboard layout (sidebar)
    ├── dashboard/page.tsx # /dashboard
    └── settings/page.tsx  # /settings

Marketing Layout

This layout provides the standard website structure with header and footer. It wraps all pages in the marketing route group.

// app/(marketing)/layout.tsx
import Header from "@/components/layout/Header";
import Footer from "@/components/layout/Footer";

export default function MarketingLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <>
      <Header />
      <main className="min-h-screen">{children}</main>
      <Footer />
    </>
  );
}

Auth Layout

The auth layout provides a centered, minimal design perfect for login and registration forms where you want users to focus on the task at hand.

// app/(auth)/layout.tsx
export default function AuthLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="min-h-screen flex items-center justify-center bg-gray-50">
      <div className="w-full max-w-md">{children}</div>
    </div>
  );
}

Dashboard Layout

The dashboard layout includes a sidebar for navigation and a header for user actions. This structure is typical for application interfaces.

// app/(dashboard)/layout.tsx
import Sidebar from "@/components/layout/Sidebar";
import DashboardHeader from "@/components/layout/DashboardHeader";

export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="min-h-screen flex">
      <Sidebar />
      <div className="flex-1 flex flex-col">
        <DashboardHeader />
        <main className="flex-1 p-6 bg-gray-50">{children}</main>
      </div>
    </div>
  );
}

3. Navigation

Next.js provides multiple ways to navigate between pages. The Link component handles client-side navigation with prefetching, while the useRouter hook enables programmatic navigation.

Link Component

The Link component is the primary way to navigate between pages. It automatically prefetches linked pages in the viewport, making navigation instant.

import Link from "next/link";

export default function Navigation() {
  return (
    <nav>
      {/* Basic link */}
      <Link href="/">Home</Link>

      {/* Dynamic route */}
      <Link href="/transactions/123">View Transaction</Link>

      {/* With query parameters */}
      <Link href="/services?category=airtime">Airtime</Link>

      {/* Object syntax */}
      <Link
        href={{
          pathname: "/services/[category]",
          query: { category: "airtime" },
        }}
      >
        Airtime
      </Link>

      {/* Replace history (no back button) */}
      <Link href="/dashboard" replace>
        Dashboard
      </Link>

      {/* Scroll to top disabled */}
      <Link href="/about" scroll={false}>
        About
      </Link>

      {/* Prefetch disabled */}
      <Link href="/heavy-page" prefetch={false}>
        Heavy Page
      </Link>
    </nav>
  );
}

useRouter Hook (Client Component)

The useRouter hook provides programmatic navigation for cases where you need to navigate in response to events or conditions. Remember this only works in Client Components.

"use client";

import { useRouter } from "next/navigation";

export default function NavigationButtons() {
  const router = useRouter();

  return (
    <div>
      {/* Navigate programmatically */}
      <button onClick={() => router.push("/dashboard")}>Go to Dashboard</button>

      {/* Replace current history entry */}
      <button onClick={() => router.replace("/login")}>Login</button>

      {/* Go back */}
      <button onClick={() => router.back()}>Back</button>

      {/* Go forward */}
      <button onClick={() => router.forward()}>Forward</button>

      {/* Refresh current route */}
      <button onClick={() => router.refresh()}>Refresh</button>
    </div>
  );
}

usePathname & useSearchParams

These hooks provide access to the current URL information. usePathname returns the current path, while useSearchParams gives you access to query string parameters.

"use client";

import { usePathname, useSearchParams } from "next/navigation";

export default function CurrentRoute() {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  const category = searchParams.get("category");

  return (
    <div>
      <p>Current path: {pathname}</p>
      <p>Category: {category}</p>
    </div>
  );
}

4. Active Link States

Creating active link states improves navigation UX by showing users where they are in the application. This custom NavLink component compares the current path with the link's href.

NavLink Component

This reusable component wraps Next.js Link and adds active state styling. The exact prop determines whether to match the path exactly or use prefix matching.

// components/ui/NavLink.tsx
"use client";

import Link from "next/link";
import { usePathname } from "next/navigation";
import { cn } from "@/lib/utils";

interface NavLinkProps {
  href: string;
  children: React.ReactNode;
  exact?: boolean;
}

export default function NavLink({
  href,
  children,
  exact = false,
}: NavLinkProps) {
  const pathname = usePathname();

  const isActive = exact ? pathname === href : pathname.startsWith(href);

  return (
    <Link
      href={href}
      className={cn(
        "px-4 py-2 rounded-lg transition-colors",
        isActive ? "bg-primary text-white" : "text-gray-600 hover:bg-gray-100"
      )}
    >
      {children}
    </Link>
  );
}

Usage

Here is how to use the NavLink component in a sidebar. The exact prop on Dashboard ensures it only highlights when on that exact path, not on nested routes.

// components/layout/Sidebar.tsx
"use client";

import NavLink from "@/components/ui/NavLink";

const navItems = [
  { href: "/dashboard", label: "Dashboard", exact: true },
  { href: "/wallet", label: "Wallet" },
  { href: "/transactions", label: "Transactions" },
  { href: "/services", label: "Services" },
  { href: "/settings", label: "Settings" },
];

export default function Sidebar() {
  return (
    <aside className="w-64 bg-white border-r p-4">
      <nav className="space-y-2">
        {navItems.map((item) => (
          <NavLink key={item.href} href={item.href} exact={item.exact}>
            {item.label}
          </NavLink>
        ))}
      </nav>
    </aside>
  );
}

5. Redirects

Redirects send users to a different URL. Next.js provides several ways to implement redirects depending on whether you need them at request time or as permanent configurations.

In Server Components

The redirect function from next/navigation performs a server-side redirect. It is commonly used for authentication checks or when data determines the user should be elsewhere.

import { redirect } from "next/navigation";

export default async function ProtectedPage() {
  const session = await getSession();

  if (!session) {
    redirect("/login");
  }

  return <div>Protected content</div>;
}

In Route Handlers

Route handlers can also use the redirect function to send users to a different page after processing, such as after an OAuth callback.

// app/api/auth/callback/route.ts
import { redirect } from "next/navigation";

export async function GET(request: Request) {
  // Process OAuth callback...

  redirect("/dashboard");
}

Configuration Redirects

For permanent redirects that should be handled at the routing level, add them to next.config.ts. These are ideal for URL migrations or legacy route handling.

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  async redirects() {
    return [
      {
        source: "/old-page",
        destination: "/new-page",
        permanent: true, // 308 status
      },
      {
        source: "/blog/:slug",
        destination: "/articles/:slug",
        permanent: false, // 307 status
      },
    ];
  },
};

export default nextConfig;

6. Loading & Error States

Next.js provides special files for handling loading and error states. These create a better user experience by showing appropriate feedback during transitions and when errors occur.

Loading UI

The loading.tsx file automatically wraps your page in a Suspense boundary. The skeleton UI displays immediately while the page data loads.

// app/(dashboard)/transactions/loading.tsx
export default function Loading() {
  return (
    <div className="space-y-4">
      <div className="h-8 w-48 bg-gray-200 animate-pulse rounded" />
      <div className="space-y-2">
        {[...Array(5)].map((_, i) => (
          <div key={i} className="h-16 bg-gray-200 animate-pulse rounded" />
        ))}
      </div>
    </div>
  );
}

Error UI

The error.tsx file creates an error boundary for the route segment. It must be a Client Component and receives the error and a reset function to retry rendering.

// app/(dashboard)/transactions/error.tsx
"use client";

interface ErrorProps {
  error: Error & { digest?: string };
  reset: () => void;
}

export default function Error({ error, reset }: ErrorProps) {
  return (
    <div className="p-6 text-center">
      <h2 className="text-xl font-bold text-red-600 mb-4">
        Something went wrong!
      </h2>
      <p className="text-gray-600 mb-4">{error.message}</p>
      <button
        onClick={reset}
        className="px-4 py-2 bg-primary text-white rounded"
      >
        Try again
      </button>
    </div>
  );
}

Not Found

The not-found.tsx file displays when a resource is not found. This provides a better experience than a generic 404 page by being contextual to the route.

// app/not-found.tsx
import Link from "next/link";

export default function NotFound() {
  return (
    <div className="min-h-screen flex items-center justify-center">
      <div className="text-center">
        <h1 className="text-6xl font-bold text-gray-900 mb-4">404</h1>
        <p className="text-xl text-gray-600 mb-8">Page not found</p>
        <Link href="/" className="px-6 py-3 bg-primary text-white rounded-lg">
          Go Home
        </Link>
      </div>
    </div>
  );
}

Trigger Not Found

Use the notFound function to programmatically trigger the not-found page when a resource does not exist. This is cleaner than throwing an error.

import { notFound } from "next/navigation";

export default async function TransactionPage({ params }: Props) {
  const { id } = await params;
  const transaction = await getTransaction(id);

  if (!transaction) {
    notFound();
  }

  return <div>{transaction.type}</div>;
}

7. Query Parameters

Query parameters allow you to pass additional data through the URL. They are commonly used for filters, pagination, and search functionality.

Reading Query Params

In Server Components, searchParams is a Promise that provides access to URL query parameters. This allows you to filter data on the server before rendering.

// app/services/page.tsx
type Props = {
  searchParams: Promise<{ category?: string; page?: string }>;
};

export default async function ServicesPage({ searchParams }: Props) {
  const { category, page } = await searchParams;

  return (
    <div>
      <p>Category: {category || "all"}</p>
      <p>Page: {page || "1"}</p>
    </div>
  );
}

Updating Query Params (Client)

This pattern creates a filter component that updates the URL without a full page reload. Creating a new URLSearchParams object and pushing to the router triggers a server re-render.

"use client";

import { useRouter, useSearchParams, usePathname } from "next/navigation";

export default function Filters() {
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();

  const updateFilter = (key: string, value: string) => {
    const params = new URLSearchParams(searchParams.toString());

    if (value) {
      params.set(key, value);
    } else {
      params.delete(key);
    }

    router.push(`${pathname}?${params.toString()}`);
  };

  return (
    <div className="flex gap-4">
      <select
        value={searchParams.get("category") || ""}
        onChange={(e) => updateFilter("category", e.target.value)}
      >
        <option value="">All Categories</option>
        <option value="airtime">Airtime</option>
        <option value="data">Data</option>
        <option value="electricity">Electricity</option>
      </select>

      <select
        value={searchParams.get("status") || ""}
        onChange={(e) => updateFilter("status", e.target.value)}
      >
        <option value="">All Statuses</option>
        <option value="pending">Pending</option>
        <option value="completed">Completed</option>
        <option value="failed">Failed</option>
      </select>
    </div>
  );
}

Additional Resources

Next Lesson: Server & Client Components