تبها (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) |
|---|---|---|---|
value | string | undefined | مقدار کنترلشده تب فعال. |
defaultValue | string | undefined | مقدار پیشفرض تب فعال (غیرکنترلشده). |
onValueChange | (value: string) => void | undefined | تابع فراخوانی هنگام تغییر تب فعال. |
disabled | boolean | false | غیرفعال کردن تمام تبها و جلوگیری از تغییر. |
variant | "underline" | "pill" | "underline" | نوع ظاهری تبها (خط زیرین یا قرصی). |
size | "sm" | "md" | "lg" | "md" | اندازه تبها و تایپوگرافی آنها. |
fullWidth | boolean | false | در صورت فعال بودن، تبها عرض در دسترس را به صورت مساوی پر میکنند. |
className | string | - | کلاسهای CSS سفارشی برای روت کامپوننت. |
TabsList
لیست افقی تبها که به عنوان نوار ناوبری عمل میکند.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
justify | "start" | "center" | "between" | "start" | چیدمان افقی تبها در لیست. |
variant | "underline" | "pill" | "underline" | نوع ظاهری لیست تبها. مقدار پیشفرض را از Tabs به ارث میبرد. |
size | "sm" | "md" | "lg" | "md" | اندازه تبها. مقدار پیشفرض را از Tabs به ارث میبرد. |
fullWidth | boolean | false | در صورت فعال بودن، لیست تبها تمام عرض را میگیرد. |
className | string | - | کلاسهای CSS سفارشی. |
TabsTrigger
دکمهای که برای فعال کردن یک تب خاص استفاده میشود.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
value | string | - | شناسه یکتای تب که باید با TabsContent متناظر باشد. |
disabled | boolean | false | غیرفعال کردن این تب و جلوگیری از انتخاب آن. |
variant | "underline" | "pill" | "underline" | نوع ظاهری این تب. مقدار پیشفرض را از Tabs به ارث میبرد. |
size | "sm" | "md" | "lg" | "md" | اندازه این تب. مقدار پیشفرض را از Tabs به ارث میبرد. |
fullWidth | boolean | false | در صورت فعال بودن، این تب عرض در دسترس را پر میکند. |
className | string | - | کلاسهای CSS سفارشی. |
TabsContent
پنل محتوایی که متناظر با هر تب نمایش داده میشود.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
value | string | - | شناسه تب که محتوای این پنل را به Trigger متناظر متصل میکند. |
className | string | - | کلاسهای 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}