مسیر (Breadcrumb)

نمایش مسیر به منبع فعلی با سلسله‌مراتب لینک‌ها. با پشتیبانی RTL، جداکننده سفارشی و حالت جمع‌شده (Ellipsis).

نصب (Installation)

1npx @quark-lab/rad-ui add breadcrumb

نمونه‌ها (Examples)

نمونه پایه (Basic)

مسیر ساده با لینک خانه، کامپوننت‌ها و صفحه فعلی. از asChild و Link برای روتینگ استفاده شده.

مشاهده کد

1import Link from "next/link";
2import {
3  Breadcrumb,
4  BreadcrumbItem,
5  BreadcrumbLink,
6  BreadcrumbList,
7  BreadcrumbPage,
8  BreadcrumbSeparator,
9} from "@/components/ui/breadcrumb";
10
11export default function BasicBreadcrumb() {
12  return (
13    <Breadcrumb>
14      <BreadcrumbList>
15        <BreadcrumbItem>
16          <BreadcrumbLink asChild>
17            <Link href="/">خانه</Link>
18          </BreadcrumbLink>
19        </BreadcrumbItem>
20        <BreadcrumbSeparator />
21        <BreadcrumbItem>
22          <BreadcrumbLink asChild>
23            <Link href="/components">کامپوننت‌ها</Link>
24          </BreadcrumbLink>
25        </BreadcrumbItem>
26        <BreadcrumbSeparator />
27        <BreadcrumbItem>
28          <BreadcrumbPage>مسیر (نان‌خور)</BreadcrumbPage>
29        </BreadcrumbItem>
30      </BreadcrumbList>
31    </Breadcrumb>
32  );
33}

جداکننده سفارشی (Custom separator)

با قرار دادن children در BreadcrumbSeparator می‌توان جداکننده را سفارشی کرد (مثلاً /).

مشاهده کد

1import Link from "next/link";
2import {
3  Breadcrumb,
4  BreadcrumbItem,
5  BreadcrumbLink,
6  BreadcrumbList,
7  BreadcrumbPage,
8  BreadcrumbSeparator,
9} from "@/components/ui/breadcrumb";
10
11export default function CustomSeparatorBreadcrumb() {
12  return (
13    <Breadcrumb>
14      <BreadcrumbList>
15        <BreadcrumbItem>
16          <BreadcrumbLink asChild>
17            <Link href="/">خانه</Link>
18          </BreadcrumbLink>
19        </BreadcrumbItem>
20        <BreadcrumbSeparator>/</BreadcrumbSeparator>
21        <BreadcrumbItem>
22          <BreadcrumbLink asChild>
23            <Link href="/components">کامپوننت‌ها</Link>
24          </BreadcrumbLink>
25        </BreadcrumbItem>
26        <BreadcrumbSeparator>/</BreadcrumbSeparator>
27        <BreadcrumbItem>
28          <BreadcrumbPage>مسیر</BreadcrumbPage>
29        </BreadcrumbItem>
30      </BreadcrumbList>
31    </Breadcrumb>
32  );
33}

حالت جمع‌شده (Collapsed)

با BreadcrumbEllipsis و DropdownMenu می‌توان بخشی از مسیر را جمع کرد.

مشاهده کد

1import Link from "next/link";
2import {
3  Breadcrumb,
4  BreadcrumbItem,
5  BreadcrumbEllipsis,
6  BreadcrumbLink,
7  BreadcrumbList,
8  BreadcrumbPage,
9  BreadcrumbSeparator,
10} from "@/components/ui/breadcrumb";
11import {
12  DropdownMenu,
13  DropdownMenuContent,
14  DropdownMenuItem,
15  DropdownMenuTrigger,
16} from "@/components/ui/dropdown-menu";
17import { Button } from "@/components/ui/button";
18
19export default function CollapsedBreadcrumb() {
20  return (
21    <Breadcrumb>
22      <BreadcrumbList>
23        <BreadcrumbItem>
24          <BreadcrumbLink asChild>
25            <Link href="/">خانه</Link>
26          </BreadcrumbLink>
27        </BreadcrumbItem>
28        <BreadcrumbSeparator />
29        <BreadcrumbItem>
30          <DropdownMenu>
31            <DropdownMenuTrigger className="flex items-center gap-1">
32              <BreadcrumbEllipsis />
33            </DropdownMenuTrigger>
34            <DropdownMenuContent align="start">
35              <DropdownMenuItem asChild>
36                <Link href="/docs">مستندات</Link>
37              </DropdownMenuItem>
38              <DropdownMenuItem asChild>
39                <Link href="/components">کامپوننت‌ها</Link>
40              </DropdownMenuItem>
41            </DropdownMenuContent>
42          </DropdownMenu>
43        </BreadcrumbItem>
44        <BreadcrumbSeparator />
45        <BreadcrumbItem>
46          <BreadcrumbPage>مسیر</BreadcrumbPage>
47        </BreadcrumbItem>
48      </BreadcrumbList>
49    </Breadcrumb>
50  );
51}

مرجع API (API Reference)

Breadcrumb

المان ریشه ناوبری که همه اجزای مسیر را در بر می‌گیرد (nav با aria-label).

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`className`	`string`	`-`	کلاس‌های CSS سفارشی

BreadcrumbList

لیست مرتب (ol) آیتم‌های مسیر.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`className`	`string`	`-`	کلاس‌های CSS سفارشی

BreadcrumbItem

هر آیتم مسیر (li).

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`className`	`string`	`-`	کلاس‌های CSS سفارشی

BreadcrumbLink

لینک قابل کلیک. با asChild می‌توان از Link یا کامپوننت روتینگ استفاده کرد.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`asChild`	`boolean`	`false`	با true می‌توان از المان فرزند (مثلاً Link) به‌عنوان رندر نهایی استفاده کرد.
`className`	`string`	`-`	کلاس‌های CSS سفارشی

BreadcrumbPage

صفحه فعلی (غیرقابل کلیک)، با role و aria-current.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`className`	`string`	`-`	کلاس‌های CSS سفارشی

BreadcrumbSeparator

جداکننده بین آیتم‌ها. با children می‌توان آیکون یا متن را عوض کرد.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`children`	`React.ReactNode`	`ChevronRight`	اجزای جداکننده سفارشی (پیش‌فرض: آیکون ChevronRight)
`className`	`string`	`-`	کلاس‌های CSS سفارشی

BreadcrumbEllipsis

نشانگر حالت جمع‌شده برای مسیرهای طولانی.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`className`	`string`	`-`	کلاس‌های CSS سفارشی

دسترسی‌پذیری (Accessibility)

ساختار معنایی

از nav با aria-label="breadcrumb" و ol / li برای سازگاری با خوانندگان صفحه و الگوی Breadcrumb در WAI-ARIA استفاده شده است.

صفحه فعلی

BreadcrumbPage دارای aria-current="page" و aria-disabled="true" است.

پشتیبانی RTL

آیکون جداکننده پیش‌فرض (ChevronRight) با rtl:rotate-180 در جهت راست‌به‌چپ درست نمایش داده می‌شود.

بهترین شیوه‌ها (Best Practices)

چه زمانی از مسیر استفاده کنیم؟

صفحات چندسطحی (مثلاً فروشگاه → دسته‌بندی → محصول).
ساختار سلسله‌مراتبی وب‌سایت برای ناوبری و SEO.
نمایش مسیر بازگشت به صفحه قبلی یا سطح بالاتر.

لینک با روتینگ

برای اپ‌های Next یا React Router از BreadcrumbLink asChild و قرار دادن Link به‌عنوان فرزند استفاده کنید تا ناوبری سمت کلاینت درست کار کند.

مسیرهای طولانی

با BreadcrumbEllipsis و یک منوی کشویی می‌توان بخشی از آیتم‌ها را جمع کرد تا از شلوغی جلوگیری شود.

نحوه استفاده (Usage)

1import Link from "next/link";
2import {
3  Breadcrumb,
4  BreadcrumbItem,
5  BreadcrumbLink,
6  BreadcrumbList,
7  BreadcrumbPage,
8  BreadcrumbSeparator,
9} from "@/components/ui/breadcrumb";
10
11export default function BreadcrumbUsage() {
12  return (
13    <Breadcrumb>
14      <BreadcrumbList>
15        <BreadcrumbItem>
16          <BreadcrumbLink asChild>
17            <Link href="/">خانه</Link>
18          </BreadcrumbLink>
19        </BreadcrumbItem>
20        <BreadcrumbSeparator />
21        <BreadcrumbItem>
22          <BreadcrumbLink asChild>
23            <Link href="/components">کامپوننت‌ها</Link>
24          </BreadcrumbLink>
25        </BreadcrumbItem>
26        <BreadcrumbSeparator />
27        <BreadcrumbItem>
28          <BreadcrumbPage>مسیر (نان‌خور)</BreadcrumbPage>
29        </BreadcrumbItem>
30      </BreadcrumbList>
31    </Breadcrumb>
32  );
33}

مثال‌های پیشرفته (Advanced Examples)

جداکننده سفارشی (Custom separator)

استفاده از کاراکتر / به‌جای آیکون پیش‌فرض.

مشاهده کد

1import Link from "next/link";
2import {
3  Breadcrumb,
4  BreadcrumbItem,
5  BreadcrumbLink,
6  BreadcrumbList,
7  BreadcrumbPage,
8  BreadcrumbSeparator,
9} from "@/components/ui/breadcrumb";
10
11export default function CustomSeparatorBreadcrumb() {
12  return (
13    <Breadcrumb>
14      <BreadcrumbList>
15        <BreadcrumbItem>
16          <BreadcrumbLink asChild>
17            <Link href="/">خانه</Link>
18          </BreadcrumbLink>
19        </BreadcrumbItem>
20        <BreadcrumbSeparator>/</BreadcrumbSeparator>
21        <BreadcrumbItem>
22          <BreadcrumbLink asChild>
23            <Link href="/components">کامپوننت‌ها</Link>
24          </BreadcrumbLink>
25        </BreadcrumbItem>
26        <BreadcrumbSeparator>/</BreadcrumbSeparator>
27        <BreadcrumbItem>
28          <BreadcrumbPage>مسیر</BreadcrumbPage>
29        </BreadcrumbItem>
30      </BreadcrumbList>
31    </Breadcrumb>
32  );
33}

حالت جمع‌شده با منو (Collapsed with dropdown)

مسیر طولانی با BreadcrumbEllipsis و DropdownMenu.

مشاهده کد

1import Link from "next/link";
2import {
3  Breadcrumb,
4  BreadcrumbItem,
5  BreadcrumbEllipsis,
6  BreadcrumbLink,
7  BreadcrumbList,
8  BreadcrumbPage,
9  BreadcrumbSeparator,
10} from "@/components/ui/breadcrumb";
11import {
12  DropdownMenu,
13  DropdownMenuContent,
14  DropdownMenuItem,
15  DropdownMenuTrigger,
16} from "@/components/ui/dropdown-menu";
17import { Button } from "@/components/ui/button";
18
19export default function CollapsedBreadcrumb() {
20  return (
21    <Breadcrumb>
22      <BreadcrumbList>
23        <BreadcrumbItem>
24          <BreadcrumbLink asChild>
25            <Link href="/">خانه</Link>
26          </BreadcrumbLink>
27        </BreadcrumbItem>
28        <BreadcrumbSeparator />
29        <BreadcrumbItem>
30          <DropdownMenu>
31            <DropdownMenuTrigger className="flex items-center gap-1">
32              <BreadcrumbEllipsis />
33            </DropdownMenuTrigger>
34            <DropdownMenuContent align="start">
35              <DropdownMenuItem asChild>
36                <Link href="/docs">مستندات</Link>
37              </DropdownMenuItem>
38              <DropdownMenuItem asChild>
39                <Link href="/components">کامپوننت‌ها</Link>
40              </DropdownMenuItem>
41            </DropdownMenuContent>
42          </DropdownMenu>
43        </BreadcrumbItem>
44        <BreadcrumbSeparator />
45        <BreadcrumbItem>
46          <BreadcrumbPage>مسیر</BreadcrumbPage>
47        </BreadcrumbItem>
48      </BreadcrumbList>
49    </Breadcrumb>
50  );
51}