کارت پیش نمایش (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) |
|---|---|---|---|
open | boolean | undefined | وضعیت باز/بسته بودن (کنترلشده) |
defaultOpen | boolean | false | وضعیت پیشفرض (غیرکنترلشده) |
onOpenChange | (open: boolean) => void | undefined | تابع فراخوانی هنگام تغییر وضعیت |
openDelay | number | 700 | تاخیر باز شدن به میلیثانیه |
closeDelay | number | 300 | تاخیر بسته شدن به میلیثانیه |
HoverCardContent
پراپهای کامپوننت HoverCardContent.
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
side | "top" | "bottom" | "left" | "right" | "bottom" | جهت نمایش کارت نسبت به تریگر |
sideOffset | number | 4 | فاصله از تریگر به پیکسل |
align | "start" | "center" | "end" | "center" | تراز کارت نسبت به تریگر |
alignOffset | number | 0 | آفست تراز به پیکسل |
دسترسیپذیری (Accessibility)
رفتار هاور (Hover Behavior)
این کامپوننت فقط با هاور ماوس فعال میشود و برای کاربران صفحهلمسی یا کیبورد قابل دسترس نیست. از این کامپوننت برای اطلاعات ضروری استفاده نکنید
تاخیر پیشفرض (Default Delay)
تاخیر پیشفرض ۷۰۰ms برای باز شدن به کاربران اجازه میدهد بدون فعالسازی ناخواسته از روی المانها عبور کنند
محدودیتها (Limitations)
این کامپوننت جایگزین Tooltip نیست. برای اطلاعات کوتاه و ضروری که باید با کیبورد هم قابل دسترس باشد، از Tooltip استفاده کنید
بهترین شیوهها (Best Practices)
اطلاعات تکمیلی (Supplementary Info)
از HoverCard برای نمایش اطلاعات تکمیلی و غیرضروری استفاده کنید. اطلاعات نمایش داده شده نباید برای تکمیل یک تسک حیاتی باشد
پیشنمایش محتوا (Preview)
این کامپوننت برای پیشنمایش محتوای پشت یک لینک مناسب است، مثل پروفایل کاربر، جزئیات محصول، یا خلاصه مقاله
تعامل با ماوس (Mouse Only)
به یاد داشته باشید که این کامپوننت فقط با ماوس کار میکند. برای دستگاههای لمسی، محتوای کارت باید از طریق کلیک روی لینک قابل دسترس باشد
تاخیر مناسب (Proper Delay)
تاخیر پیشفرض را خیلی کم نکنید تا کاربران هنگام عبور از روی المانها با پاپآپهای ناخواسته مواجه نشوند