تب‌ها (Tabs)

کامپوننت تب برای جابه‌جایی بین نماهای مرتبط در یک فضا، با پشتیبانی کامل از RTL و حالت افقی.

نصب (Installation)

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

نمونه‌ها (Examples)

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

ساده‌ترین حالت استفاده از تب‌ها برای جابه‌جایی بین چند بخش مرتبط.

محتوای مربوط به حساب کاربری
مشاهده کد
1import { Tabs, TabsList, TabsTrigger, TabsContent } from "@/components/ui/tabs";
2
3export default function BasicTabsExample() {
4  return (
5    <Tabs defaultValue="account">
6      <TabsList>
7        <TabsTrigger value="account">حساب کاربری</TabsTrigger>
8        <TabsTrigger value="password">رمز عبور</TabsTrigger>
9        <TabsTrigger value="billing">صورتحساب</TabsTrigger>
10      </TabsList>
11      <TabsContent value="account">
12        محتوای مربوط به حساب کاربری
13      </TabsContent>
14      <TabsContent value="password">
15        محتوای مربوط به تغییر رمز عبور
16      </TabsContent>
17      <TabsContent value="billing">
18        محتوای مربوط به اطلاعات صورتحساب
19      </TabsContent>
20    </Tabs>
21  );
22}
23

با آیکون (With Icons)

استفاده از آیکون در کنار متن تب‌ها. در RTL از کلاس‌های ms/me برای فاصله استفاده کنید.

محتوای حساب کاربری
مشاهده کد
1import {
2  Tabs,
3  TabsList,
4  TabsTrigger,
5  TabsContent,
6} from "@/components/ui/tabs";
7import { User, Lock, CreditCard } from "lucide-react";
8
9export default function TabsWithIconsExample() {
10  return (
11    <Tabs defaultValue="account">
12      <TabsList>
13        <TabsTrigger value="account">
14          <User className="h-4 w-4 ms-2" />
15          حساب کاربری
16        </TabsTrigger>
17        <TabsTrigger value="password">
18          <Lock className="h-4 w-4 ms-2" />
19          رمز عبور
20        </TabsTrigger>
21        <TabsTrigger value="billing">
22          <CreditCard className="h-4 w-4 ms-2" />
23          صورتحساب
24        </TabsTrigger>
25      </TabsList>
26      <TabsContent value="account">محتوای حساب کاربری</TabsContent>
27      <TabsContent value="password">محتوای تنظیمات رمز عبور</TabsContent>
28      <TabsContent value="billing">محتوای صورتحساب</TabsContent>
29    </Tabs>
30  );
31}
32

پر کردن عرض (Full Width) (Full Width)

تب‌هایی که عرض در دسترس را به صورت مساوی بین خود تقسیم می‌کنند.

محتوای نمای کلی
مشاهده کد
1import {
2  Tabs,
3  TabsList,
4  TabsTrigger,
5  TabsContent,
6} from "@/components/ui/tabs";
7
8export default function FullWidthTabsExample() {
9  return (
10    <Tabs defaultValue="overview" fullWidth>
11      <TabsList>
12        <TabsTrigger value="overview">نمای کلی</TabsTrigger>
13        <TabsTrigger value="analytics">آنالیتیکس</TabsTrigger>
14        <TabsTrigger value="settings">تنظیمات</TabsTrigger>
15      </TabsList>
16      <TabsContent value="overview">محتوای نمای کلی</TabsContent>
17      <TabsContent value="analytics">محتوای آنالیتیکس</TabsContent>
18      <TabsContent value="settings">محتوای تنظیمات</TabsContent>
19    </Tabs>
20  );
21}
22

حالت غیرفعال (Disabled State)

غیرفعال کردن یک تب خاص برای جلوگیری از دسترسی موقت.

محتوای حساب کاربری
مشاهده کد
1import {
2  Tabs,
3  TabsList,
4  TabsTrigger,
5  TabsContent,
6} from "@/components/ui/tabs";
7
8export default function DisabledTabsExample() {
9  return (
10    <Tabs defaultValue="account">
11      <TabsList>
12        <TabsTrigger value="account">حساب کاربری</TabsTrigger>
13        <TabsTrigger value="password" disabled>
14          رمز عبور (غیرفعال)
15        </TabsTrigger>
16        <TabsTrigger value="billing">صورتحساب</TabsTrigger>
17      </TabsList>
18      <TabsContent value="account">محتوای حساب کاربری</TabsContent>
19      <TabsContent value="password">این تب غیرفعال است</TabsContent>
20      <TabsContent value="billing">محتوای صورتحساب</TabsContent>
21    </Tabs>
22  );
23}
24

مرجع API (API Reference)

Tabs

کامپوننت ریشه که وضعیت انتخاب تب‌ها را مدیریت می‌کند.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
valuestringundefinedمقدار کنترل‌شده تب فعال.
defaultValuestringundefinedمقدار پیش‌فرض تب فعال (غیرکنترل‌شده).
onValueChange(value: string) => voidundefinedتابع فراخوانی هنگام تغییر تب فعال.
disabledbooleanfalseغیرفعال کردن تمام تب‌ها و جلوگیری از تغییر.
variant"underline" | "pill""underline"نوع ظاهری تب‌ها (خط زیرین یا قرصی).
size"sm" | "md" | "lg""md"اندازه تب‌ها و تایپوگرافی آن‌ها.
fullWidthbooleanfalseدر صورت فعال بودن، تب‌ها عرض در دسترس را به صورت مساوی پر می‌کنند.
classNamestring-کلاس‌های CSS سفارشی برای روت کامپوننت.

TabsList

لیست افقی تب‌ها که به عنوان نوار ناوبری عمل می‌کند.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
justify"start" | "center" | "between""start"چیدمان افقی تب‌ها در لیست.
variant"underline" | "pill""underline"نوع ظاهری لیست تب‌ها. مقدار پیش‌فرض را از Tabs به ارث می‌برد.
size"sm" | "md" | "lg""md"اندازه تب‌ها. مقدار پیش‌فرض را از Tabs به ارث می‌برد.
fullWidthbooleanfalseدر صورت فعال بودن، لیست تب‌ها تمام عرض را می‌گیرد.
classNamestring-کلاس‌های CSS سفارشی.

TabsTrigger

دکمه‌ای که برای فعال کردن یک تب خاص استفاده می‌شود.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
valuestring-شناسه یکتای تب که باید با TabsContent متناظر باشد.
disabledbooleanfalseغیرفعال کردن این تب و جلوگیری از انتخاب آن.
variant"underline" | "pill""underline"نوع ظاهری این تب. مقدار پیش‌فرض را از Tabs به ارث می‌برد.
size"sm" | "md" | "lg""md"اندازه این تب. مقدار پیش‌فرض را از Tabs به ارث می‌برد.
fullWidthbooleanfalseدر صورت فعال بودن، این تب عرض در دسترس را پر می‌کند.
classNamestring-کلاس‌های CSS سفارشی.

TabsContent

پنل محتوایی که متناظر با هر تب نمایش داده می‌شود.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
valuestring-شناسه تب که محتوای این پنل را به Trigger متناظر متصل می‌کند.
classNamestring-کلاس‌های CSS سفارشی.

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

کیبورد (Keyboard)

  • Tab - ورود به نوار تب‌ها یا خروج از آن.
  • ArrowRight و ArrowLeft - جابه‌جایی بین تب‌های مجاور در نوار افقی.
  • Home - رفتن به اولین تب.
  • End - رفتن به آخرین تب.

نقش‌های ARIA (ARIA Roles)

نوار تب‌ها از نقش tablist و هر تب از نقش tab استفاده می‌کند. محتوای هر تب نیز با tabpanel مشخص می‌شود.

مدیریت فوکوس (Focus Management)

فوکوس فقط روی تب فعال قرار می‌گیرد و با کلیدهای جهت‌دار بین تب‌ها جابه‌جا می‌شود. تب‌های غیرفعال از فوکوس و انتخاب جلوگیری می‌کنند.

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

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

  • زمانی که چند نما یا دسته‌بندی مرتبط دارید که باید در یک صفحه واحد نمایش داده شوند.
  • برای جابه‌جایی بین تنظیمات، جزئیات پروفایل یا نماهای تحلیل مختلف.
  • اگر محتوای هر بخش کاملاً مستقل است، از چند صفحه جداگانه به جای تب استفاده کنید.

برچسب‌ها و آیکون‌ها در RTL

متن تب‌ها را کوتاه و روشن نگه دارید. برای قرار دادن آیکون در سمت راست متن در RTL از ms-2 و برای سمت چپ از me-2 استفاده کنید.

تعداد تب‌ها

از بیش از ۵–۷ تب در یک نوار خودداری کنید. برای تعداد بیشتر، از منوها یا ناوبری‌های تو در تو استفاده کنید.

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

1import {
2  Tabs,
3  TabsList,
4  TabsTrigger,
5  TabsContent,
6} from "@/components/ui/tabs";
7
8export default function TabsUsageExample() {
9  return (
10    <Tabs defaultValue="account" fullWidth>
11      <TabsList>
12        <TabsTrigger value="account">حساب کاربری</TabsTrigger>
13        <TabsTrigger value="password">رمز عبور</TabsTrigger>
14        <TabsTrigger value="billing">صورتحساب</TabsTrigger>
15      </TabsList>
16
17      <TabsContent value="account">
18        <p>محتوای مرتبط با حساب کاربری.</p>
19      </TabsContent>
20      <TabsContent value="password">
21        <p>فرم تغییر رمز عبور.</p>
22      </TabsContent>
23      <TabsContent value="billing">
24        <p>لیست فاکتورها و اطلاعات صورتحساب.</p>
25      </TabsContent>
26    </Tabs>
27  );
28}
29

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

تب‌ها داخل کارت (Tabs in Card)

استفاده از تب‌ها درون یک کارت برای ساخت فرم‌ها و داشبوردهای پیچیده.

محتوای مرتبط با حساب کاربری.

مشاهده کد
1import {
2  Tabs,
3  TabsList,
4  TabsTrigger,
5  TabsContent,
6} from "@/components/ui/tabs";
7import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
8
9export default function TabsInCardExample() {
10  return (
11    <Card>
12      <CardHeader>
13        <CardTitle>تنظیمات حساب</CardTitle>
14      </CardHeader>
15      <CardContent>
16        <Tabs defaultValue="profile">
17          <TabsList>
18            <TabsTrigger value="profile">پروفایل</TabsTrigger>
19            <TabsTrigger value="security">امنیت</TabsTrigger>
20          </TabsList>
21          <TabsContent value="profile">
22            {/* محتوای پروفایل */}
23          </TabsContent>
24          <TabsContent value="security">
25            {/* محتوای امنیت */}
26          </TabsContent>
27        </Tabs>
28      </CardContent>
29    </Card>
30  );
31}