Breadcrumb

کامپوننت Breadcrumb برای نمایش مسیر ناوبری صفحه‌ی فعلی استفاده می‌شود؛ مثل «خانه / محصولات / جزئیات محصول». به کاربر نشان می‌دهد کجای سلسله‌مراتب سایت است و امکان بازگشت سریع به سطح‌های بالاتر را می‌دهد.

Import

import { Breadcrumb } from "fara-ui";

اگر هنوز FaraUI را نصب و راه‌اندازی نکرده‌ای، ابتدا صفحه‌ی شروع به کار را ببین.

Basic Usage

<Breadcrumb
  items={[
    { label: "خانه", href: "/" },
    { label: "محصولات", href: "/products" },
    { label: "لپ‌تاپ" },
  ]}
/>

Playground

separator

صفحه‌ی فعلی

<Breadcrumb
  items={[
    { label: "خانه", href: "/" },
    { label: "محصولات", href: "/products" },
    { label: "لپ‌تاپ گیمینگ" },
  ]}
/>

Items

هر آیتم از نوع BreadcrumbItem است:

• label (الزامی) — متن آیتم
• href — لینک آیتم؛ برای آیتم‌های میانی
• onClick — به‌جای href، برای ناوبری با router (مثلاً navigate در React Router)

آیتم آخر همیشه صفحه‌ی فعلی در نظر گرفته می‌شود و به‌صورت متن (بدون لینک) با استایل متمایز نمایش داده می‌شود.

برای ثبت یک رویداد جانبی می‌توانی onClick را کنار href قرار بدهی:

<Breadcrumb
  items={[
    {
      label: "خانه",
      href: "/",
      onClick: () => analytics.track("breadcrumb_home"),
    },
    { label: "تنظیمات" },
  ]}
/>

در TypeScript فعلی نوع onClick بدون آرگومان تعریف شده است و آیتم‌های قبل از current همیشه <a> هستند. برای ناوبری کامل با router، بهتر است API کامپوننت به handler استاندارد لینک یا امکان رندر سفارشی ارتقا پیدا کند.

Separator

جداکننده‌ی پیش‌فرض / است و با prop قابل تغییر است — مثلاً "›" یا "—".

Breadcrumb vs Tabs

• Breadcrumb — ناوبری بین سطح‌های سلسله‌مراتبی (عمق صفحه)
• Tabs — سوییچ بین نمای‌های هم‌سطح از یک صفحه

Accessibility

• کامپوننت با <nav aria-label="مسیر ناوبری"> و <ol> پیاده شده تا ساختار مسیر برای screen reader ها معنادار باشد.
• آیتم آخر با aria-current="page" علامت می‌خورد.
• برای آیتم‌های قبل از current، label کوتاه و توصیفی انتخاب کن؛ جداکننده صرفاً بصری است و به‌عنوان لینک رندر نمی‌شود.

Data Attributes and Customize CSS

Breadcrumb hookهای پایدار زیر را ارائه می‌کند:

Attribute	کاربرد
data-fara-breadcrumb	ریشه‌ی nav
data-fara-breadcrumb-list	لیست <ol>
data-fara-breadcrumb-item	هر آیتم
data-current	روی آخرین آیتم
data-fara-breadcrumb-current	متن صفحه‌ی فعلی
data-fara-breadcrumb-link	لینک آیتم‌های قبلی
data-fara-breadcrumb-separator	جداکننده بین آیتم‌ها

<Breadcrumb
  className="page-breadcrumb"
  items={[
    { label: "خانه", href: "/" },
    { label: "گزارش‌ها", href: "/reports" },
    { label: "امروز" },
  ]}
/>

[data-fara-breadcrumb] {
  font-size: 0.875rem;
}

[data-fara-breadcrumb-item][data-current] [data-fara-breadcrumb-current] {
  font-weight: 700;
  color: #0f172a;
}

[data-fara-breadcrumb-separator] {
  margin-inline: 8px;
  color: #94a3b8;
}

className روی nav ریشه اعمال می‌شود و برای layout یا استایل یک breadcrumb خاص مناسب است.

Props

Prop	Type	Default	Description
items	BreadcrumbItem[]	-	مسیر ناوبری (الزامی)
separator	string	"/"	جداکننده‌ی بین آیتم‌ها
className	string	-	کلاس CSS اضافی برای سفارشی‌سازی

interface BreadcrumbItem {
  label: string; // الزامی
  href?: string;
  onClick?: () => void;
}