تولتیپ (Tooltip)

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

نصب (Installation)

npx @quark-lab/rad-ui add tooltip

نکته مهم: باید TooltipProvider را در ریشه برنامه خود اضافه کنید. این کار قبلاً در layout.tsx انجام شده است.

نمونه‌ها (Examples)

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

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

مشاهده کد

1import {
2  Tooltip,
3  TooltipContent,
4  TooltipTrigger,
5} from "@/components/ui/tooltip";
6import { Button } from "@/components/ui/button";
7
8export default function BasicTooltip() {
9  return (
10    <Tooltip>
11      <TooltipTrigger asChild>
12        <Button variant="outline">هاور کنید</Button>
13      </TooltipTrigger>
14      <TooltipContent>
15        <p>افزودن به کتابخانه</p>
16      </TooltipContent>
17    </Tooltip>
18  );
19}

جهت (Side)

استفاده از پراپ side برای تغییر موقعیت تولتیپ.

مشاهده کد

1import {
2  Tooltip,
3  TooltipContent,
4  TooltipTrigger,
5} from "@/components/ui/tooltip";
6import { Button } from "@/components/ui/button";
7
8export default function SideTooltip() {
9  return (
10    <div className="flex flex-wrap gap-4">
11      <Tooltip>
12        <TooltipTrigger asChild>
13          <Button variant="outline">چپ</Button>
14        </TooltipTrigger>
15        <TooltipContent side="left">
16          <p>نمایش از سمت چپ</p>
17        </TooltipContent>
18      </Tooltip>
19
20      <Tooltip>
21        <TooltipTrigger asChild>
22          <Button variant="outline">بالا</Button>
23        </TooltipTrigger>
24        <TooltipContent side="top">
25          <p>نمایش از بالا</p>
26        </TooltipContent>
27      </Tooltip>
28
29      <Tooltip>
30        <TooltipTrigger asChild>
31          <Button variant="outline">پایین</Button>
32        </TooltipTrigger>
33        <TooltipContent side="bottom">
34          <p>نمایش از پایین</p>
35        </TooltipContent>
36      </Tooltip>
37
38      <Tooltip>
39        <TooltipTrigger asChild>
40          <Button variant="outline">راست</Button>
41        </TooltipTrigger>
42        <TooltipContent side="right">
43          <p>نمایش از سمت راست</p>
44        </TooltipContent>
45      </Tooltip>
46    </div>
47  );
48}

با کلید میانبر (With Keyboard Shortcut)

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

مشاهده کد

1import {
2  Tooltip,
3  TooltipContent,
4  TooltipTrigger,
5} from "@/components/ui/tooltip";
6import { Button } from "@/components/ui/button";
7import { Kbd } from "@/components/ui/kbd";
8
9export default function WithKbdTooltip() {
10  return (
11    <Tooltip>
12      <TooltipTrigger asChild>
13        <Button variant="outline">
14          جستجو
15          <Kbd className="ms-2">Ctrl</Kbd>
16          <Kbd>K</Kbd>
17        </Button>
18      </TooltipTrigger>
19      <TooltipContent>
20        <p>جستجوی سریع</p>
21      </TooltipContent>
22    </Tooltip>
23  );
24}

دکمه غیرفعال (Disabled Button)

نمایش تولتیپ روی دکمه غیرفعال با استفاده از span wrapper.

مشاهده کد

1import {
2  Tooltip,
3  TooltipContent,
4  TooltipTrigger,
5} from "@/components/ui/tooltip";
6import { Button } from "@/components/ui/button";
7
8export default function DisabledButtonTooltip() {
9  return (
10    <Tooltip>
11      <TooltipTrigger asChild>
12        <span className="inline-block">
13          <Button disabled>غیرفعال</Button>
14        </span>
15      </TooltipTrigger>
16      <TooltipContent>
17        <p>این دکمه غیرفعال است</p>
18      </TooltipContent>
19    </Tooltip>
20  );
21}

مرجع API (API Reference)

TooltipProvider

ارائه‌دهنده زمینه برای تولتیپ‌ها. باید در ریشه برنامه قرار گیرد.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`delayDuration`	`number`	`700`	تاخیر نمایش به میلی‌ثانیه
`skipDelayDuration`	`number`	`300`	تاخیر بین نمایش چند تولتیپ متوالی
`disableHoverableContent`	`boolean`	`false`	غیرفعال کردن تعامل با محتوای تولتیپ

Tooltip

کامپوننت اصلی که به عنوان کانتینر برای تولتیپ عمل می‌کند.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`open`	`boolean`	`undefined`	وضعیت باز/بسته بودن (کنترل‌شده)
`defaultOpen`	`boolean`	`false`	وضعیت پیش‌فرض (غیرکنترل‌شده)
`onOpenChange`	`(open: boolean) => void`	`undefined`	تابع فراخوانی هنگام تغییر وضعیت

TooltipTrigger

عنصری که تولتیپ را فعال می‌کند. معمولاً یک دکمه یا لینک است.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`className`	`string`	`-`	کلاس‌های CSS سفارشی

TooltipContent

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

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`side`	`"top" \| "bottom" \| "left" \| "right"`	`"top"`	جهت نمایش تولتیپ نسبت به تریگر
`sideOffset`	`number`	`4`	فاصله از تریگر به پیکسل
`align`	`"start" \| "center" \| "end"`	`"center"`	تراز تولتیپ نسبت به تریگر
`alignOffset`	`number`	`0`	آفست تراز به پیکسل
`className`	`string`	`-`	کلاس‌های CSS سفارشی

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

پشتیبانی از کیبورد (Keyboard Support)

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

پشتیبانی از RTL

تمام کامپوننت‌ها از ویژگی‌های منطقی CSS استفاده می‌کنند و در هر دو جهت RTL و LTR به درستی کار می‌کنند.

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

تولتیپ به صورت خودکار با فوکوس و هاور مدیریت می‌شود و از استانداردهای WAI-ARIA پیروی می‌کند.

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

استفاده از TooltipProvider

TooltipProvider باید در ریشه برنامه قرار گیرد تا تمام تولتیپ‌ها بتوانند از تنظیمات مشترک استفاده کنند. این کار در layout.tsx انجام شده است.

محتوا

مختصر: تولتیپ باید متن کوتاه و مفید داشته باشد
مکمل: اطلاعات تکمیلی که در رابط اصلی نیست
غیرضروری: از تولتیپ برای اطلاعات ضروری استفاده نکنید

دکمه‌های غیرفعال

برای نمایش تولتیپ روی دکمه‌های غیرفعال، دکمه را در یک span با asChild قرار دهید تا رویدادهای ماوس به درستی کار کنند.

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

نمونه کامل از نحوه ایمپورت و استفاده از کامپوننت تولتیپ.

مشاهده کد

1import {
2  Tooltip,
3  TooltipContent,
4  TooltipTrigger,
5} from "@/components/ui/tooltip";
6import { Button } from "@/components/ui/button";
7
8export default function MyComponent() {
9  return (
10    <Tooltip>
11      <TooltipTrigger asChild>
12        <Button variant="outline">هاور کنید</Button>
13      </TooltipTrigger>
14      <TooltipContent>
15        <p>افزودن به کتابخانه</p>
16      </TooltipContent>
17    </Tooltip>
18  );
19}

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

جهت (Side)

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

مشاهده کد

1import {
2  Tooltip,
3  TooltipContent,
4  TooltipTrigger,
5} from "@/components/ui/tooltip";
6import { Button } from "@/components/ui/button";
7
8export default function SideTooltip() {
9  return (
10    <div className="flex flex-wrap gap-4">
11      <Tooltip>
12        <TooltipTrigger asChild>
13          <Button variant="outline">چپ</Button>
14        </TooltipTrigger>
15        <TooltipContent side="left">
16          <p>نمایش از سمت چپ</p>
17        </TooltipContent>
18      </Tooltip>
19
20      <Tooltip>
21        <TooltipTrigger asChild>
22          <Button variant="outline">بالا</Button>
23        </TooltipTrigger>
24        <TooltipContent side="top">
25          <p>نمایش از بالا</p>
26        </TooltipContent>
27      </Tooltip>
28
29      <Tooltip>
30        <TooltipTrigger asChild>
31          <Button variant="outline">پایین</Button>
32        </TooltipTrigger>
33        <TooltipContent side="bottom">
34          <p>نمایش از پایین</p>
35        </TooltipContent>
36      </Tooltip>
37
38      <Tooltip>
39        <TooltipTrigger asChild>
40          <Button variant="outline">راست</Button>
41        </TooltipTrigger>
42        <TooltipContent side="right">
43          <p>نمایش از سمت راست</p>
44        </TooltipContent>
45      </Tooltip>
46    </div>
47  );
48}

با کلید میانبر (With Keyboard Shortcut)

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

مشاهده کد

1import {
2  Tooltip,
3  TooltipContent,
4  TooltipTrigger,
5} from "@/components/ui/tooltip";
6import { Button } from "@/components/ui/button";
7import { Kbd } from "@/components/ui/kbd";
8
9export default function WithKbdTooltip() {
10  return (
11    <Tooltip>
12      <TooltipTrigger asChild>
13        <Button variant="outline">
14          جستجو
15          <Kbd className="ms-2">Ctrl</Kbd>
16          <Kbd>K</Kbd>
17        </Button>
18      </TooltipTrigger>
19      <TooltipContent>
20        <p>جستجوی سریع</p>
21      </TooltipContent>
22    </Tooltip>
23  );
24}

دکمه غیرفعال (Disabled Button)

نمایش تولتیپ روی دکمه‌های غیرفعال.

مشاهده کد

1import {
2  Tooltip,
3  TooltipContent,
4  TooltipTrigger,
5} from "@/components/ui/tooltip";
6import { Button } from "@/components/ui/button";
7
8export default function DisabledButtonTooltip() {
9  return (
10    <Tooltip>
11      <TooltipTrigger asChild>
12        <span className="inline-block">
13          <Button disabled>غیرفعال</Button>
14        </span>
15      </TooltipTrigger>
16      <TooltipContent>
17        <p>این دکمه غیرفعال است</p>
18      </TooltipContent>
19    </Tooltip>
20  );
21}