Badge
برچسبی کوچک برای نمایش وضعیت، دستهبندی یا شمارنده در کنار عناصر دیگر؛ یا نقطهای که روی گوشهٔ یک عنصر (مثل آواتار) مینشیند.
این کامپوننت فعلاً برای ۱ فریمورک از ۴ فریمورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
نصب
با CLI اختصاصی dig-ui کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگیها و فایلها خودکار اضافه میشوند.
pnpm dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/badge.jsonnpx dig-ui@latest add https://design-system-tau-green.vercel.app/r/badge.jsonyarn dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/badge.jsonbunx --bun dig-ui@latest add https://design-system-tau-green.vercel.app/r/badge.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
استفاده
import { Badge } from "@/components/ui/badge"
<Badge color="success">تایید شده</Badge>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
ترکیب اجزا
رنگ Badge با دو محور مستقل کار میکند، درست مثل Button و Alert.
محور color فقط چهار متغیر CSS را ست میکند — --badge، --badge-foreground، --badge-subtle و --badge-subtle-foreground — و محور variant تصمیم میگیرد این رنگ کجا بنشیند: پسزمینهٔ توپر، پسزمینهٔ خنثی با متن رنگی، پسزمینهٔ ملایم یا فقط حاشیه. افزودن رنگ تازه یعنی یک سطر در محور color، نه یک ردیف compound بهازای هر حالت بصری.
- وقتی Badge بدون فرزند رندر شود — یا
dotصریحاًtrueباشد — به یک نقطهٔ توپر بدون متن تبدیل میشود. - برای نشستن روی گوشهٔ یک عنصر دیگر (مثل شمارندهٔ اعلان روی آواتار)، عنصر لنگر و Badge را داخل BadgeAnchor بگذارید و به Badge یک
placementبدهید.
دسترسپذیری
- بهصورت پیشفرض یک span تزئینی است؛ اگر نشان تنها راه انتقال یک وضعیت است، متن آن را برای صفحهخوان هم واضح بنویسید.
- برای نشانهای قابلکلیک، از asChild همراه با یک Link یا button استفاده کنید تا نقش تعاملی درست اعلام شود.
- نشان نقطهای (dot) هیچ متنی ندارد؛ اگر وضعیتی را منتقل میکند (مثل آنلاین/آفلاین) یک aria-label روی BadgeAnchor یا عنصر لنگر بگذارید تا صفحهخوان هم آن را بفهمد.
مرجع API
Badge
تمام ویژگیهای استاندارد span نیز پشتیبانی میشود.
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| variant | "default" | "secondary" | "soft" | "outline" | "default" | حالت بصری نشان؛ تعیین میکند رنگ کجا بنشیند. |
| color | "default" | "primary" | "success" | "warning" | "destructive" | "default" | رنگ معنایی، مستقل از حالت. default یعنی همان ظاهر خنثای دیگ. |
| size | "sm" | "default" | "lg" | "default" | اندازهٔ نشان. |
| dot | boolean | — | بهصورت پیشفرض وقتی فرزندی داده نشود خودکار true میشود؛ برای اجبار به شکل نقطهای حتی با فرزند، صریحاً true بدهید. |
| placement | "top-end" | "top-start" | "bottom-end" | "bottom-start" | — | وقتی داخل BadgeAnchor باشد، Badge را روی همان گوشه از عنصر لنگر مینشاند (مطلقموقعیت). |
| asChild | boolean | false | رندر استایلها روی فرزند مستقیم بهجای تگ span. |
BadgeAnchor
قاب موقعیتدهی برای Badgeهای anchorشده؛ یک span با position: relative که عنصر لنگر و Badge را کنار هم نگه میدارد.
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| children | React.ReactNode | — | عنصر لنگر (مثل Avatar یا Button) بهعلاوهٔ خود Badge. |
| className | string | — | کلاسهای تکمیلی برای قاب لنگر. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
نمونهها
Variants
چهار حالت بصری، مستقل از رنگ: default پسزمینهٔ توپر رنگی، secondary پسزمینهٔ خنثی با متن رنگی، soft پسزمینهٔ ملایم رنگی و outline فقط حاشیهٔ رنگی که با هاور پر میشود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Colors
پنج رنگ معنایی: default برای وضعیت خنثی، primary برای نشان برند، success، warning و destructive.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Sizes
سه اندازه: sm، default و lg.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Dot Badge
نشانی بدون متن (فرزند خالی) بهصورت خودکار به یک نقطهٔ توپر تبدیل میشود، برای وضعیت آنلاین/آفلاین یا نشانگر فعالیت.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Dot Badge on Avatar
همان نشان نقطهای، اینبار روی گوشهٔ آواتار با BadgeAnchor؛ ترکیب رایج برای نشاندادن وضعیت یک کاربر.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Placements (Anchor)
با BadgeAnchor، Badge روی گوشهٔ عنصر لنگر مینشیند؛ چهار موقعیت منطقی (نه چپ/راست فیزیکی) که با راستبهچپ خودکار همجهت میشوند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
With Content
Badge متن، عدد یا آیکون را میپذیرد؛ فاصله و اندازهٔ آیکون خودکار با اندازهٔ Badge هماهنگ میشود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
رنگ تنها حامل معنا نباشد
بجِ بیمتن برای کاربر کوررنگ و کاربر صفحهخوان هیچ معنایی ندارد. متن را بنویسید و رنگ را تقویتکننده نگه دارید، نه حاملِ تنهای معنا.
نادرست: فقط رنگ، برای کاربر کوررنگ بیمعنی است
درست: رنگ تقویتکننده است، نه حاملِ تنهای معنا
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
متن بلند (Overflow)
بج برای یک یا دو کلمه است. اگر جملهای دارید که باید کامل خوانده شود، جایش بج نیست؛ متن معمولی یا Alert بگذارید. اگر ناچارید، عرض بیشینه و truncate بدهید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار میآید |
|---|---|
| Variants | چهار حالت بصری، مستقل از رنگ: default پسزمینهٔ توپر رنگی، secondary پسزمینهٔ خنثی با متن رنگی، soft پسزمینهٔ ملایم رنگی و outline فقط حاشیهٔ رنگی که با هاور پر میشود. |
| Colors | پنج رنگ معنایی: default برای وضعیت خنثی، primary برای نشان برند، success، warning و destructive. |
| Sizes | سه اندازه: sm، default و lg. |
| Dot Badge | نشانی بدون متن (فرزند خالی) بهصورت خودکار به یک نقطهٔ توپر تبدیل میشود، برای وضعیت آنلاین/آفلاین یا نشانگر فعالیت. |
| Dot Badge on Avatar | همان نشان نقطهای، اینبار روی گوشهٔ آواتار با BadgeAnchor؛ ترکیب رایج برای نشاندادن وضعیت یک کاربر. |
| Placements (Anchor) | با BadgeAnchor، Badge روی گوشهٔ عنصر لنگر مینشیند؛ چهار موقعیت منطقی (نه چپ/راست فیزیکی) که با راستبهچپ خودکار همجهت میشوند. |
| With Content | Badge متن، عدد یا آیکون را میپذیرد؛ فاصله و اندازهٔ آیکون خودکار با اندازهٔ Badge هماهنگ میشود. |
| رنگ تنها حامل معنا نباشد | ستون وضعیت در فهرستها |
| متن بلند (Overflow) | وضعیتهایی که شرحشان طولانی است |
دستورالعمل استفاده
رنگ متناسب با معنای وضعیت
انجام بده
color را بر اساس معنای واقعی وضعیت انتخاب کنید؛ success برای چیزی که واقعاً تایید یا کامل شده.
انجام نده
رنگ destructive برای یک وضعیت خنثی مثل «پیشنویس» به کاربر میگوید مشکلی وجود دارد، در حالی که ندارد.
برای نشان قابلکلیک از asChild استفاده کنید
انجام بده
با asChild، Badge استایلش را روی یک عنصر تعاملی واقعی مثل button میگذارد؛ نقش، فوکوس و کلیک صفحهکلید درست کار میکند.
انجام نده
یک span معمولی هرچقدر هم شبیه دکمه بهنظر برسد، نه با Tab فوکوس میگیرد و نه نقش تعاملی برای صفحهخوان دارد.
متن کوتاه، نه جمله
انجام بده
یک یا دو کلمه برای نشان کافی است؛ شکل قرصی Badge برای متن کوتاه طراحی شده.
انجام نده
جملهٔ بلند داخل Badge از شکل فشردهٔ آن بیرون میزند و در کنار متن دیگر بد مینشیند.