آیتم (Item)

یک کامپوننت همه‌کاره برای نمایش محتوا شامل تصویر، عنوان، توضیحات و اقدامات.

نصب (Installation)

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

نمونه‌ها (Examples)

استفاده پایه (Basic Usage)

ساده‌ترین حالت استفاده از آیتم.

ورود بیومتریک

برای ورود از چهره یا اثر انگشت خود استفاده کنید.

مشاهده کد
1import {
2  Item,
3  ItemContent,
4  ItemDescription,
5  ItemMedia,
6  ItemTitle,
7} from "@/components/ui/item"
8import { ScanFace } from "lucide-react"
9
10export function BasicItem() {
11  return (
12    <Item>
13      <ItemMedia>
14        <ScanFace className="h-5 w-5" />
15      </ItemMedia>
16      <ItemContent>
17        <ItemTitle>ورود بیومتریک</ItemTitle>
18        <ItemDescription>
19          برای ورود از چهره یا اثر انگشت خود استفاده کنید.
20        </ItemDescription>
21      </ItemContent>
22    </Item>
23  )
24}
25

انواع (Variants)

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

پیش‌فرض (Default)

ظاهر استاندارد آیتم.

خط دور (Outline)

استایل با خط دور برای تاکید بیشتر.

خاموش (Muted)

پس‌زمینه ملایم برای اهمیت کمتر.

روح (Ghost)

استایل روح برای ظاهری تمیز و مینیمال.

مشاهده کد
1import {
2  Item,
3  ItemContent,
4  ItemDescription,
5  ItemMedia,
6  ItemTitle,
7} from "@/components/ui/item"
8import { Mail, Shield, Smartphone } from "lucide-react"
9
10export function ItemVariants() {
11  return (
12    <div className="flex flex-col gap-4 w-full">
13      <Item variant="default">
14        <ItemMedia>
15          <Smartphone className="h-5 w-5" />
16        </ItemMedia>
17        <ItemContent>
18          <ItemTitle>پیش‌فرض (Default)</ItemTitle>
19          <ItemDescription>ظاهر استاندارد آیتم.</ItemDescription>
20        </ItemContent>
21      </Item>
22
23      <Item variant="outline">
24        <ItemMedia>
25          <Shield className="h-5 w-5" />
26        </ItemMedia>
27        <ItemContent>
28          <ItemTitle>خط دور (Outline)</ItemTitle>
29          <ItemDescription>
30            استایل با خط دور برای تاکید بیشتر.
31          </ItemDescription>
32        </ItemContent>
33      </Item>
34
35      <Item variant="muted">
36        <ItemMedia>
37          <Mail className="h-5 w-5" />
38        </ItemMedia>
39        <ItemContent>
40          <ItemTitle>خاموش (Muted)</ItemTitle>
41          <ItemDescription>
42            پس‌زمینه ملایم برای اهمیت کمتر.
43          </ItemDescription>
44        </ItemContent>
45      </Item>
46
47       <Item variant="ghost">
48        <ItemMedia>
49          <Mail className="h-5 w-5" />
50        </ItemMedia>
51        <ItemContent>
52          <ItemTitle>روح (Ghost)</ItemTitle>
53          <ItemDescription>
54            استایل روح برای ظاهری تمیز و مینیمال.
55          </ItemDescription>
56        </ItemContent>
57      </Item>
58    </div>
59  )
60}
61

اندازه‌ها (Sizes)

کنترل فاصله داخلی آیتم‌ها با پراپ size.

اندازه پیش‌فرض

فاصله‌گذاری استاندارد.

اندازه کوچک (Small)

چیدمان فشرده برای لیست‌های متراکم.

خیلی کوچک (XS)

حداقل فضای اشغالی.

مشاهده کد
1import {
2  Item,
3  ItemContent,
4  ItemDescription,
5  ItemMedia,
6  ItemTitle,
7} from "@/components/ui/item"
8import { Bell, BellRing, Volume2 } from "lucide-react"
9
10export function ItemSizes() {
11  return (
12    <div className="flex flex-col gap-4 w-full">
13      <Item size="default" variant="outline">
14        <ItemMedia>
15          <Bell className="h-5 w-5" />
16        </ItemMedia>
17        <ItemContent>
18          <ItemTitle>اندازه پیش‌فرض</ItemTitle>
19          <ItemDescription>فاصله‌گذاری استاندارد.</ItemDescription>
20        </ItemContent>
21      </Item>
22
23      <Item size="sm" variant="outline">
24        <ItemMedia>
25          <BellRing className="h-4 w-4" />
26        </ItemMedia>
27        <ItemContent>
28          <ItemTitle>اندازه کوچک (Small)</ItemTitle>
29          <ItemDescription>چیدمان فشرده برای لیست‌های متراکم.</ItemDescription>
30        </ItemContent>
31      </Item>
32
33      <Item size="xs" variant="outline">
34        <ItemMedia className="h-8 w-8">
35          <Volume2 className="h-3 w-3" />
36        </ItemMedia>
37        <ItemContent>
38          <ItemTitle className="text-xs">خیلی کوچک (XS)</ItemTitle>
39          <ItemDescription className="text-xs">حداقل فضای اشغالی.</ItemDescription>
40        </ItemContent>
41      </Item>
42    </div>
43  )
44}
45

با اقدامات (With Actions)

استفاده از ItemActions برای قرار دادن دکمه‌ها.

تنظیمات زبان

زبان مورد نظر خود را تغییر دهید.

تنظیمات حساب

مدیریت پروفایل کاربری.

مشاهده کد
1import {
2  Item,
3  ItemActions,
4  ItemContent,
5  ItemDescription,
6  ItemMedia,
7  ItemTitle,
8} from "@/components/ui/item"
9import { Button } from "@/components/ui/button"
10import { Globe, Settings } from "lucide-react"
11
12export function ItemWithActions() {
13  return (
14    <div className="flex flex-col gap-4 w-full">
15      <Item variant="outline">
16        <ItemMedia>
17          <Globe className="h-5 w-5" />
18        </ItemMedia>
19        <ItemContent>
20          <ItemTitle>تنظیمات زبان</ItemTitle>
21          <ItemDescription>زبان مورد نظر خود را تغییر دهید.</ItemDescription>
22        </ItemContent>
23        <ItemActions>
24          <Button variant="outline" size="sm">
25            تغییر
26          </Button>
27        </ItemActions>
28      </Item>
29
30      <Item variant="outline">
31        <ItemMedia>
32          <Settings className="h-5 w-5" />
33        </ItemMedia>
34        <ItemContent>
35          <ItemTitle>تنظیمات حساب</ItemTitle>
36          <ItemDescription>مدیریت پروفایل کاربری.</ItemDescription>
37        </ItemContent>
38        <ItemActions>
39          <Button size="sm">مدیریت</Button>
40        </ItemActions>
41      </Item>
42    </div>
43  )
44}
45

انواع رسانه (Media Types)

استایل‌دهی متفاوت برای آیکون، تصویر و آواتار.

نوع آیکون (Icon)

رسانه با پس‌زمینه شفاف.

کاربر

نوع تصویر (Image)

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

کاربر

نوع آواتار (Avatar)

رسانه دایره‌ای شکل.

مشاهده کد
1import {
2  Item,
3  ItemContent,
4  ItemDescription,
5  ItemMedia,
6  ItemTitle,
7} from "@/components/ui/item"
8import { Camera } from "lucide-react"
9
10export function ItemMediaTypes() {
11  return (
12    <div className="flex flex-col gap-4 w-full">
13      <Item variant="outline">
14        <ItemMedia variant="icon">
15           <Camera className="h-5 w-5" />
16        </ItemMedia>
17        <ItemContent>
18          <ItemTitle>نوع آیکون (Icon)</ItemTitle>
19          <ItemDescription>رسانه با پس‌زمینه شفاف.</ItemDescription>
20        </ItemContent>
21      </Item>
22
23      <Item variant="outline">
24        <ItemMedia variant="image">
25           <img
26            src="https://github.com/shadcn.png"
27            alt="کاربر"
28            className="h-full w-full object-cover"
29          />
30        </ItemMedia>
31        <ItemContent>
32          <ItemTitle>نوع تصویر (Image)</ItemTitle>
33          <ItemDescription>رسانه با گوشه‌های گرد شده.</ItemDescription>
34        </ItemContent>
35      </Item>
36
37      <Item variant="outline">
38        <ItemMedia variant="avatar">
39          <img
40            src="https://github.com/shadcn.png"
41            alt="کاربر"
42            className="h-full w-full object-cover"
43          />
44        </ItemMedia>
45        <ItemContent>
46          <ItemTitle>نوع آواتار (Avatar)</ItemTitle>
47          <ItemDescription>رسانه دایره‌ای شکل.</ItemDescription>
48        </ItemContent>
49      </Item>
50    </div>
51  )
52}
53

گروه‌بندی (Grouping)

استفاده از ItemGroup و ItemSeparator برای لیست آیتم‌ها.

پروفایل

مشاهده اطلاعات کاربری.

تنظیمات

مدیریت تنظیمات برنامه.

صورت‌حساب

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

مشاهده کد
1import {
2  Item,
3  ItemContent,
4  ItemDescription,
5  ItemGroup,
6  ItemMedia,
7  ItemSeparator,
8  ItemTitle,
9} from "@/components/ui/item"
10import { CreditCard, Settings, User } from "lucide-react"
11
12export function ItemGroupExample() {
13  return (
14    <div className="w-full max-w-md border rounded-xl p-2">
15      <ItemGroup>
16        <Item>
17          <ItemMedia>
18            <User className="h-5 w-5" />
19          </ItemMedia>
20          <ItemContent>
21            <ItemTitle>پروفایل</ItemTitle>
22            <ItemDescription>مشاهده اطلاعات کاربری.</ItemDescription>
23          </ItemContent>
24        </Item>
25        
26        <ItemSeparator />
27        
28        <Item>
29          <ItemMedia>
30            <Settings className="h-5 w-5" />
31          </ItemMedia>
32          <ItemContent>
33            <ItemTitle>تنظیمات</ItemTitle>
34            <ItemDescription>مدیریت تنظیمات برنامه.</ItemDescription>
35          </ItemContent>
36        </Item>
37
38        <ItemSeparator />
39
40        <Item>
41          <ItemMedia>
42             <CreditCard className="h-5 w-5" />
43          </ItemMedia>
44          <ItemContent>
45            <ItemTitle>صورت‌حساب</ItemTitle>
46            <ItemDescription>مدیریت پرداخت‌ها و فاکتورها.</ItemDescription>
47          </ItemContent>
48        </Item>
49      </ItemGroup>
50    </div>
51  )
52}
53

مرجع API (API Reference)

Item

پراپ‌های کامپوننت Item.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
variant"default" | "outline" | "muted" | "ghost""default"سبک ظاهری آیتم
size"default" | "sm" | "xs""default"اندازه آیتم
asChildbooleanfalseتغییر عنصر ریشه به فرزند مستقیم (برای لینک‌ها و غیره)

ItemMedia

پراپ‌های کامپوننت ItemMedia.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
variant"default" | "icon" | "image" | "avatar""default"نوع رسانه (برای تنظیم استایل مناسب)

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

این کامپوننت از المان‌های معنایی HTML (مانند div، h3، p) استفاده می‌کند و با صفحه‌خوان‌ها سازگار است.

  • اگر از asChild برای لینک دادن استفاده می‌کنید، فوکوس و تعاملات کیبورد به درستی مدیریت می‌شوند.

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

  • از ItemTitle برای عنوان اصلی و کوتاه استفاده کنید.
  • از ItemDescription برای توضیحات مکمل استفاده کنید.
  • برای لیست‌های طولانی از ItemGroup استفاده کنید تا فاصله‌گذاری و جداکننده‌ها به درستی اعمال شوند.
  • در حالت RTL، چیدمان به طور خودکار تنظیم می‌شود (تصویر در راست، اقدامات در چپ).

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

1import {
2  Item,
3  ItemActions,
4  ItemContent,
5  ItemDescription,
6  ItemMedia,
7  ItemTitle,
8} from "@/components/ui/item"
9import { Button } from "@/components/ui/button"
10import { Check } from "lucide-react"
11
12export function UsageExample() {
13  return (
14    <Item className="border rounded-md">
15      <ItemMedia>
16        <Check className="h-5 w-5" />
17      </ItemMedia>
18      <ItemContent>
19        <ItemTitle>تکمیل وظیفه</ItemTitle>
20        <ItemDescription>وظیفه با موفقیت انجام شد.</ItemDescription>
21      </ItemContent>
22      <ItemActions>
23        <Button variant="ghost" size="sm">بستن</Button>
24      </ItemActions>
25    </Item>
26  )
27}
28