Alert
پیامهای ایستا برای اطلاعرسانی، موفقیت، هشدار یا خطا؛ با شش رنگ معنایی، پنج حالت بصری و امکان بستن، در چیدمان گرید که با راستبهچپ بهصورت خودکار همجهت میشود.
این کامپوننت فعلاً برای ۱ فریمورک از ۴ فریمورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
نصب
با CLI اختصاصی dig-ui کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگیها و فایلها خودکار اضافه میشوند.
pnpm dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/alert.jsonnpx dig-ui@latest add https://design-system-tau-green.vercel.app/r/alert.jsonyarn dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/alert.jsonbunx --bun dig-ui@latest add https://design-system-tau-green.vercel.app/r/alert.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
استفاده
import { Alert, AlertTitle, AlertDescription } from "@/components/ui/alert"
import { Info } from "lucide-react"
<Alert>
<Info />
<AlertTitle>نکته</AlertTitle>
<AlertDescription>...</AlertDescription>
</Alert>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
ترکیب اجزا
دسترسپذیری
- role="alert" روی ریشهٔ کامپوننت قرار دارد تا محتوا بهصورت یک ناحیهٔ زندهٔ (live region) به صفحهخوان اعلام شود.
- برای پیامهای غیرفوری (مثلاً نکات راهنما) در نظر بگیرید که آیا واقعاً نیاز به اعلام فوری دارید یا نه.
- دکمهٔ بستن بهصورت پیشفرض aria-label="بستن" دارد؛ اگر متن دیگری مناسبتر است با کلاس روی dismissible نمیشود عوضش کرد، در این حالت بهجای dismissible یک دکمهٔ بستن دستی داخل Alert بگذارید.
- وقتی Alert بسته میشود، کاملاً از DOM حذف میشود (نه فقط مخفی)، پس صفحهخوان دیگر آن را نمیبیند.
مرجع API
Alert
تمام ویژگیهای استاندارد div نیز پشتیبانی میشود.
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| variant | "default" | "solid" | "bordered" | "flat" | "faded" | "default" | حالت بصری Alert؛ تعیین میکند رنگ کجا بنشیند. |
| color | "default" | "primary" | "info" | "success" | "warning" | "destructive" | "default" | رنگ معنایی، مستقل از حالت. default یعنی همان ظاهر خنثای دیگ. |
| radius | "none" | "sm" | "md" | "lg" | "full" | "lg" | شعاع گوشه. |
| dismissible | boolean | false | دکمهٔ بستن را نشان میدهد. |
| open | boolean | — | حالت کنترلشدهٔ نمایش؛ اگر ندهید، Alert خودش وضعیت را نگه میدارد. |
| defaultOpen | boolean | true | حالت اولیهٔ نمایش وقتی کنترلنشده است. |
| onOpenChange | (open: boolean) => void | — | هنگام بستهشدن (کلیک روی دکمهٔ بستن) صدا زده میشود. |
| role | "alert" | "alert" | نقش ARIA برای خواندهشدن توسط صفحهخوان. |
AlertIcon
ستون اول Alert. بدون children، بر اساس color یک آیکون پیشفرض (svg داخلی، بدون وابستگی) نشان میدهد؛ با children، همان آیکون شما را نمایش میدهد.
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| children | React.ReactElement | — | آیکون دلخواه؛ اگر ندهید، آیکون پیشفرض همان color نمایش داده میشود. |
AlertTitle / AlertDescription / AlertAction
زیرکامپوننتهای اسلاتی؛ هرکدام یک div با ویژگیهای استاندارد است. AlertAction برای ردیف دکمههای اقدام است.
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| AlertTitle | React.ComponentProps<'div'> | — | عنوان کوتاه پیام. |
| AlertDescription | React.ComponentProps<'div'> | — | توضیح پیام؛ اختیاری است. |
| AlertAction | React.ComponentProps<'div'> | — | ردیف اقدام (مثلاً دکمه)، زیر عنوان/توضیح. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
نمونهها
Colors
شش رنگ معنایی: default برای پیام خنثی، primary برای معرفی/تبلیغ یک قابلیت، info برای اطلاعرسانی خنثیتر از primary (بدون رنگ برند)، success، warning و destructive.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Default Icon
با AlertIcon دیگر لازم نیست برای هر Alert آیکون انتخاب کنید، بدون children، بر اساس color یک آیکون پیشفرض نشان داده میشود. اگر آیکون دلخواه دارید همانطور که قبلاً بود مستقیم بگذارید، یا آن را داخل AlertIcon قرار دهید تا اندازهاش هماهنگ شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Variants
پنج حالت بصری، مستقل از رنگ: default (پسزمینهٔ خنثای card، همان ظاهر تاریخی)، solid (پسزمینهٔ توپر رنگی، برای اعلانهای خیلی برجسته)، bordered (فقط حاشیهٔ رنگی)، flat (پسزمینهٔ ملایم رنگی) و faded (پسزمینهٔ ملایم بهعلاوهٔ حاشیه).
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Radius
شعاع گوشه محور مستقلی است؛ پیشفرض lg همان ظاهر تاریخی Alert را حفظ میکند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Dismissible
با dismissible یک دکمهٔ بستن نمایش داده میشود؛ با کلیک، Alert کاملاً از DOM حذف میشود. برای کنترل بیرونی نمایش، از open و onOpenChange استفاده کنید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
With Action
AlertAction ردیف اقدام (مثلاً یک دکمه) را به همان ستون محتوا اضافه میکند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Title Only
AlertDescription اختیاری است؛ برای پیامهای خیلی کوتاه فقط از AlertTitle استفاده کنید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Alert یا Toast
Alert ماندگار است و جای خطایی است که کاربر باید رفعش کند؛ باید بگوید چه شد و چطور درست میشود. Toast گذراست و جای تاییدِ کاری که انجام شد. خطا را در Toast نگذارید، چون میپرد و کاربر نمیتواند دوباره بخواندش.
خطایی که کاربر باید رفعش کند، ماندگار است و باید بگوید چطور رفع میشود. برای «ذخیره شد» از Toast استفاده کنید که خودش میرود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
متن بلند با کنش (Overflow)
توضیح چندسطری اشکال ندارد، ولی کنش را داخل خودِ Alert بگذارید تا کاربر مجبور نشود دنبالش بگردد. عرض بیشینه بدهید تا سطرها بیش از حد دراز نشوند.
۹۲ درصد فضای طرح فعلی شما پر شده است. با پر شدن کامل، آپلود فایل تازه متوقف میشود ولی فایلهای موجود در دسترس میمانند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار میآید |
|---|---|
| Colors | شش رنگ معنایی: default برای پیام خنثی، primary برای معرفی/تبلیغ یک قابلیت، info برای اطلاعرسانی خنثیتر از primary (بدون رنگ برند)، success، warning و destructive. |
| Default Icon | با AlertIcon دیگر لازم نیست برای هر Alert آیکون انتخاب کنید، بدون children، بر اساس color یک آیکون پیشفرض نشان داده میشود |
| Variants | پنج حالت بصری، مستقل از رنگ: default (پسزمینهٔ خنثای card، همان ظاهر تاریخی)، solid (پسزمینهٔ توپر رنگی، برای اعلانهای خیلی برجسته)، bordered (فقط حاشیهٔ رنگی)، flat (پسزمینهٔ ملایم رنگی) و faded (پسزمینهٔ ملایم بهعلاوهٔ حاشیه). |
| Radius | شعاع گوشه محور مستقلی است؛ پیشفرض lg همان ظاهر تاریخی Alert را حفظ میکند. |
| Dismissible | با dismissible یک دکمهٔ بستن نمایش داده میشود؛ با کلیک، Alert کاملاً از DOM حذف میشود |
| With Action | AlertAction ردیف اقدام (مثلاً یک دکمه) را به همان ستون محتوا اضافه میکند. |
| Title Only | AlertDescription اختیاری است؛ برای پیامهای خیلی کوتاه فقط از AlertTitle استفاده کنید. |
| Alert یا Toast | تصمیم اول: این پیام باید بماند یا برود |
| متن بلند با کنش (Overflow) | هشداری که راهحلش یک کلیک است |
دستورالعمل استفاده
رنگ destructive فقط برای خطای واقعی
انجام بده
color destructive را برای وقتی بگذارید که کاری واقعاً شکست خورده و کاربر باید اقدام کند.
انجام نده
استفاده از رنگ خطر برای یک پیام خنثی، کاربر را بیجهت نگران میکند و اعتماد به رنگهای هشدار را کم میکند.
عنوان کوتاه و توضیح جدا
انجام بده
AlertTitle خلاصهٔ پیام است و AlertDescription جزئیات را میگوید؛ این جدایی باعث میشود پیام در یک نگاه اسکن شود.
انجام نده
ریختن کل پیام داخل AlertTitle، بدون AlertDescription، یک تیتر شلوغ و سختخوان میسازد.
Alert فقط برای پیامهایی که واقعاً باید اعلام شوند
انجام بده
چون role="alert" یک ناحیهٔ زنده است و بلافاصله توسط صفحهخوان خوانده میشود، آن را برای رویدادهای واقعی مثل خطا یا نتیجهٔ یک عمل نگه دارید.
نکته: میتوانید فیلترها را از نوار کناری تغییر دهید.
انجام نده
استفاده از Alert برای یک راهنمای ایستا و همیشگی، صفحهخوان را با اعلامهای غیرضروری خسته میکند؛ یک متن ساده کافی است.