آموزش کامل هوک usePathname در Next.js | کاربرد، نکات و مثال عملی

اگر با Next.js (App Router) کار کرده باشید، احتمالاً به این نیاز برخورد کرده‌اید که بفهمید کاربر در حال حاضر در کدام صفحه قرار دارد. برای مثال:

• لینک صفحه فعلی را با رنگ متفاوت نمایش دهید.
• بر اساس آدرس صفحه، یک کامپوننت را نمایش یا مخفی کنید.
• Breadcrumb (مسیر صفحه) بسازید.
• عنوان صفحه یا Layout را تغییر دهید.

برای انجام این کار، Next.js هوکی به نام usePathname را در اختیار ما قرار داده است.

usePathname چیست؟

usePathname یک React Hook است که از پکیج next/navigation وارد می‌شود و مسیر (Path) فعلی صفحه را به صورت رشته (String) برمی‌گرداند.

import { usePathname } from "next/navigation";

const pathname = usePathname();

console.log(pathname);

اگر آدرس مرورگر به شکل زیر باشد:

http://localhost:3000/post

مقدار pathname برابر خواهد بود با:

"/post"

اگر در صفحه اصلی باشید:

http://localhost:3000/

خروجی:

"/"

چرا به usePathname نیاز داریم؟

فرض کنید در Navbar چند لینک دارید.

کاربر وارد صفحه «پست‌ها» شده است و می‌خواهید لینک همان صفحه رنگ متفاوتی داشته باشد.

بدون usePathname باید خودتان آدرس را از window.location بخوانید که در Next.js روش مناسبی نیست.

usePathname این کار را به شکل استاندارد و هماهنگ با Router انجام می‌دهد.

مثال عملی

"use client";

import Link from "next/link";
import { usePathname } from "next/navigation";

export default function Navbar() {

    const pathname = usePathname();

    return (
        <nav>
            <Link
                href="/"
                className={
                    pathname === "/"
                        ? "text-purple-500"
                        : "text-purple-300"
                }
            >
                خانه
            </Link>

            <Link
                href="/post"
                className={
                    pathname === "/post"
                        ? "text-purple-500"
                        : "text-purple-300"
                }
            >
                پست‌ها
            </Link>
        </nav>
    );
}

در این مثال:

اگر کاربر داخل صفحه /post باشد:

pathname === "/post"

برابر با true خواهد شد و کلاس

text-purple-500

اعمال می‌شود.

اما اگر داخل صفحه دیگری باشد:

text-purple-300

نمایش داده می‌شود.

در نتیجه لینک صفحه فعال (Active Link) مشخص می‌شود.

خروجی usePathname

فرض کنید مسیرهای زیر را داریم:

همان‌طور که مشاهده می‌کنید، فقط بخش Path آدرس برگردانده می‌شود.

آیا Query String را برمی‌گرداند؟

خیر.

اگر آدرس این باشد:

/products?page=2

خروجی:

"/products"

قسمت

?page=2

برگردانده نمی‌شود.

برای دریافت Query String باید از هوک useSearchParams استفاده کنید.

آیا Hash را برمی‌گرداند؟

خیر.

اگر آدرس این باشد:

/about#team

خروجی فقط:

"/about"

خواهد بود.

مهم‌ترین نکته: فقط در Client Component قابل استفاده است

یکی از رایج‌ترین خطاهایی که توسعه‌دهندگان تازه‌کار با آن مواجه می‌شوند، استفاده از usePathname داخل Server Component است.

این هوک فقط در Client Component قابل استفاده است.

بنابراین ابتدای فایل باید بنویسید:

"use client";

سپس می‌توانید از هوک استفاده کنید.

"use client";

import { usePathname } from "next/navigation";

export default function Example() {

    const pathname = usePathname();

    return <h1>{pathname}</h1>;
}

چرا باید کامپوننت Client باشد؟

در App Router، فایل‌ها به صورت پیش‌فرض Server Component هستند.

اما usePathname به وضعیت Router مرورگر وابسته است و Router فقط داخل مرورگر (Client) وجود دارد.

سرور هنگام رندر اولیه به Router مرورگر دسترسی ندارد.

به همین دلیل Next.js اجازه استفاده از این هوک را فقط در Client Component می‌دهد.

به همین خاطر وجود دستور زیر الزامی است:

"use client";

اگر "use client" را ننویسیم چه می‌شود؟

Next.js خطایی مشابه زیر نمایش می‌دهد:

usePathname only works in Client Components.

زیرا این هوک در سمت سرور قابل اجرا نیست.

کاربردهای مهم usePathname

1. مشخص کردن لینک فعال (Active Link)

رایج‌ترین کاربرد همین مورد است.

pathname === "/dashboard"

2. ساخت Breadcrumb

فرض کنید مسیر زیر را دارید:

/products/mobile/samsung

می‌توانید با استفاده از pathname آن را به بخش‌های مختلف تقسیم کنید.

pathname.split("/")

خروجی:

[
 "",
 "products",
 "mobile",
 "samsung"
]

و از آن برای ساخت Breadcrumb استفاده کنید.

3. نمایش یا مخفی کردن کامپوننت‌ها

مثلاً نمی‌خواهید Navbar در صفحه Login نمایش داده شود.

if (pathname === "/login") {
    return null;
}

4. تغییر ظاهر Layout

مثلاً در صفحه Dashboard رنگ Header متفاوت باشد.

const bg =
    pathname.startsWith("/dashboard")
        ? "bg-black"
        : "bg-blue-600";

5. بررسی اینکه کاربر داخل یک بخش خاص هست یا خیر

مثلاً تمام صفحات Dashboard:

pathname.startsWith("/dashboard")

اگر مسیرهای زیر باشند:

/dashboard
/dashboard/users
/dashboard/settings

همگی مقدار true برمی‌گردانند.

تفاوت == و ===

در مثال شما از:

pathname == "/post"

استفاده شده است.

بهتر است همیشه از:

pathname === "/post"

استفاده کنید.

زیرا === علاوه بر مقدار، نوع داده را نیز مقایسه می‌کند و از بروز خطاهای ناخواسته جلوگیری می‌کند. در پروژه‌های React و Next.js استفاده از === یک استاندارد محسوب می‌شود.

بهترین روش نوشتن کلاس‌ها

به جای نوشتن چندباره شرط:

className={
    pathname === "/post"
        ? "text-purple-500"
        : "text-purple-300"
}

می‌توانید از کتابخانه‌هایی مانند clsx یا classnames برای مدیریت کلاس‌ها استفاده کنید تا کد خواناتر و مقیاس‌پذیرتر شود.

نکاتی که باید بدانید

• usePathname فقط مسیر (Path) را برمی‌گرداند.
• Query String را برنمی‌گرداند.
• Hash را برنمی‌گرداند.
• فقط در Client Component قابل استفاده است.
• نیاز به "use client" دارد.
• با تغییر مسیر، مقدار آن به‌صورت خودکار به‌روزرسانی می‌شود و کامپوننت دوباره رندر خواهد شد.
• برای دریافت پارامترهای Query از useSearchParams استفاده کنید.
• برای انجام عملیات ناوبری (مانند رفتن به صفحه‌ای دیگر) از useRouter استفاده کنید.

جمع‌بندی

هوک usePathname یکی از کاربردی‌ترین هوک‌های App Router در Next.js است. این هوک مسیر فعلی صفحه را در اختیار شما قرار می‌دهد و در ساخت Navbarهای هوشمند، Active Link، Breadcrumb، Layoutهای پویا و بسیاری از قابلیت‌های دیگر نقش مهمی دارد.

از آنجا که اطلاعات مسیر از Router سمت مرورگر دریافت می‌شود، استفاده از usePathname تنها در Client Component امکان‌پذیر است؛ بنابراین فراموش نکنید که در ابتدای فایل، دستور "use client" را قرار دهید.

اگر قصد دارید رابط کاربری پروژه خود را بر اساس مسیر فعلی تغییر دهید، usePathname بهترین و استانداردترین انتخاب در Next.js است.