کارت پیش نمایش (Hover Card)

کامپوننت کارت پیش نمایش برای نمایش اطلاعات تکمیلی هنگام هاور روی یک لینک یا المان استفاده می‌شود.

نصب (Installation)

1npx @quark-lab/rad-ui add hover-card

نمونه‌ها (Examples)

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

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

مشاهده کد
1import {
2  HoverCard,
3  HoverCardContent,
4  HoverCardTrigger,
5} from "@/components/ui/hover-card";
6import { Button } from "@/components/ui/button";
7
8export default function BasicExample() {
9  return (
10    <HoverCard>
11      <HoverCardTrigger asChild>
12        <Button variant="link">@radui</Button>
13      </HoverCardTrigger>
14      <HoverCardContent className="w-80">
15        <div className="flex flex-col gap-2">
16          <div className="font-semibold">@radui</div>
17          <p className="text-sm text-muted-foreground">
18            کتابخانه کامپوننت RTL-first با تم‌های ایرانی
19          </p>
20          <div className="text-xs text-muted-foreground">
21            عضویت: آذر ۱۴۰۳
22          </div>
23        </div>
24      </HoverCardContent>
25    </HoverCard>
26  );
27}
28

جهت‌های مختلف (Sides)

استفاده از پراپ side برای تعیین جهت نمایش کارت.

مشاهده کد
1import {
2  HoverCard,
3  HoverCardContent,
4  HoverCardTrigger,
5} from "@/components/ui/hover-card";
6import { Button } from "@/components/ui/button";
7
8const SIDES = ["top", "bottom", "left", "right"] as const;
9const SIDE_LABELS: Record<(typeof SIDES)[number], string> = {
10  top: "بالا",
11  bottom: "پایین",
12  left: "چپ",
13  right: "راست",
14};
15
16export default function SidesExample() {
17  return (
18    <div className="flex flex-wrap justify-center gap-2">
19      {SIDES.map((side) => (
20        <HoverCard key={side} openDelay={100} closeDelay={100}>
21          <HoverCardTrigger asChild>
22            <Button variant="outline">{SIDE_LABELS[side]}</Button>
23          </HoverCardTrigger>
24          <HoverCardContent side={side}>
25            <div className="flex flex-col gap-1">
26              <h4 className="font-medium">کارت پیش نمایش</h4>
27              <p className="text-sm text-muted-foreground">
28                این کارت در سمت {SIDE_LABELS[side]} نمایش داده می‌شود
29              </p>
30            </div>
31          </HoverCardContent>
32        </HoverCard>
33      ))}
34    </div>
35  );
36}
37

تاخیر سفارشی (Custom Delay)

تنظیم تاخیر باز و بسته شدن کارت با openDelay و closeDelay.

مشاهده کد
1import {
2  HoverCard,
3  HoverCardContent,
4  HoverCardTrigger,
5} from "@/components/ui/hover-card";
6import { Button } from "@/components/ui/button";
7
8export default function CustomDelayExample() {
9  return (
10    <HoverCard openDelay={200} closeDelay={300}>
11      <HoverCardTrigger asChild>
12        <Button variant="outline">هاور کنید</Button>
13      </HoverCardTrigger>
14      <HoverCardContent>
15        <p>این کارت با تاخیر ۲۰۰ms باز و با تاخیر ۳۰۰ms بسته می‌شود</p>
16      </HoverCardContent>
17    </HoverCard>
18  );
19}
20

با آواتار (With Avatar)

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

مشاهده کد
1import {
2  HoverCard,
3  HoverCardContent,
4  HoverCardTrigger,
5} from "@/components/ui/hover-card";
6import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
7import { Button } from "@/components/ui/button";
8
9export default function WithAvatarExample() {
10  return (
11    <HoverCard>
12      <HoverCardTrigger asChild>
13        <Button variant="link">@alikawosi</Button>
14      </HoverCardTrigger>
15      <HoverCardContent className="w-80">
16        <div className="flex gap-4">
17          <Avatar>
18            <AvatarImage src="https://github.com/shadcn.png" />
19            <AvatarFallback>AK</AvatarFallback>
20          </Avatar>
21          <div className="flex flex-col gap-1">
22            <h4 className="font-semibold">علی کاوسی</h4>
23            <p className="text-sm text-muted-foreground">
24              توسعه‌دهنده فرانت‌اند
25            </p>
26            <div className="flex items-center gap-2 text-xs text-muted-foreground">
27              <span>۱۲۳ دنبال‌کننده</span>
28              <span></span>
29              <span>۴۵ پروژه</span>
30            </div>
31          </div>
32        </div>
33      </HoverCardContent>
34    </HoverCard>
35  );
36}
37

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

کارت پروفایل کاربر (User Profile Card)

نمایش اطلاعات کامل پروفایل کاربر با آواتار و تاریخ عضویت.

مشاهده کد
1import {
2  HoverCard,
3  HoverCardContent,
4  HoverCardTrigger,
5} from "@/components/ui/hover-card";
6import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
7import { Button } from "@/components/ui/button";
8import { CalendarDays } from "lucide-react";
9
10export default function UserProfileExample() {
11  return (
12    <HoverCard>
13      <HoverCardTrigger asChild>
14        <Button variant="link" className="h-auto p-0">
15          @nextjs
16        </Button>
17      </HoverCardTrigger>
18      <HoverCardContent className="w-80">
19        <div className="flex justify-between gap-4">
20          <Avatar>
21            <AvatarImage src="https://github.com/vercel.png" />
22            <AvatarFallback>NX</AvatarFallback>
23          </Avatar>
24          <div className="flex-1 space-y-1">
25            <h4 className="text-sm font-semibold">@nextjs</h4>
26            <p className="text-sm">
27              فریم‌ورک React – ساخته و نگهداری شده توسط @vercel
28            </p>
29            <div className="flex items-center pt-2">
30              <CalendarDays className="me-2 h-4 w-4 opacity-70" />
31              <span className="text-xs text-muted-foreground">
32                عضویت از آذر ۱۴۰۰
33              </span>
34            </div>
35          </div>
36        </div>
37      </HoverCardContent>
38    </HoverCard>
39  );
40}
41

پیش‌نمایش محصول (Product Preview)

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

هدفون بی‌سیم
مشاهده کد
1import {
2  HoverCard,
3  HoverCardContent,
4  HoverCardTrigger,
5} from "@/components/ui/hover-card";
6
7export default function ProductPreviewExample() {
8  return (
9    <HoverCard>
10      <HoverCardTrigger asChild>
11        <span className="cursor-pointer underline decoration-dotted">
12          هدفون بی‌سیم
13        </span>
14      </HoverCardTrigger>
15      <HoverCardContent className="w-72">
16        <div className="flex flex-col gap-3">
17          <div className="aspect-video rounded-md bg-muted" />
18          <div>
19            <h4 className="font-semibold">هدفون بی‌سیم پرو</h4>
20            <p className="text-sm text-muted-foreground">
21              کیفیت صدای فوق‌العاده با نویز کنسلینگ فعال
22            </p>
23          </div>
24          <div className="flex items-center justify-between">
25            <span className="font-bold">۲,۵۰۰,۰۰۰ تومان</span>
26            <span className="text-xs text-green-600">موجود</span>
27          </div>
28        </div>
29      </HoverCardContent>
30    </HoverCard>
31  );
32}
33

مرجع API (API Reference)

HoverCard

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

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
openbooleanundefinedوضعیت باز/بسته بودن (کنترل‌شده)
defaultOpenbooleanfalseوضعیت پیش‌فرض (غیرکنترل‌شده)
onOpenChange(open: boolean) => voidundefinedتابع فراخوانی هنگام تغییر وضعیت
openDelaynumber700تاخیر باز شدن به میلی‌ثانیه
closeDelaynumber300تاخیر بسته شدن به میلی‌ثانیه

HoverCardContent

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

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
side"top" | "bottom" | "left" | "right""bottom"جهت نمایش کارت نسبت به تریگر
sideOffsetnumber4فاصله از تریگر به پیکسل
align"start" | "center" | "end""center"تراز کارت نسبت به تریگر
alignOffsetnumber0آفست تراز به پیکسل

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

رفتار هاور (Hover Behavior)

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

تاخیر پیش‌فرض (Default Delay)

تاخیر پیش‌فرض ۷۰۰ms برای باز شدن به کاربران اجازه می‌دهد بدون فعال‌سازی ناخواسته از روی المان‌ها عبور کنند

محدودیت‌ها (Limitations)

این کامپوننت جایگزین Tooltip نیست. برای اطلاعات کوتاه و ضروری که باید با کیبورد هم قابل دسترس باشد، از Tooltip استفاده کنید

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

اطلاعات تکمیلی (Supplementary Info)

از HoverCard برای نمایش اطلاعات تکمیلی و غیرضروری استفاده کنید. اطلاعات نمایش داده شده نباید برای تکمیل یک تسک حیاتی باشد

پیش‌نمایش محتوا (Preview)

این کامپوننت برای پیش‌نمایش محتوای پشت یک لینک مناسب است، مثل پروفایل کاربر، جزئیات محصول، یا خلاصه مقاله

تعامل با ماوس (Mouse Only)

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

تاخیر مناسب (Proper Delay)

تاخیر پیش‌فرض را خیلی کم نکنید تا کاربران هنگام عبور از روی المان‌ها با پاپ‌آپ‌های ناخواسته مواجه نشوند