البناء · جديد

زر الأيقونة

زر بأيقونة بدل النص، لأشرطة الأدوات والإجراءات المتكررة. يشارك الزر أنماطه وأحجامه وحالاته، ويحمل دائماً اسماً مكتوباً لقارئات الشاشة.

المعاينة

المعكوسة هي المحتوى الإنجليزي نفسه من اليمين إلى اليسار، لتفصل خطأ الاتجاه عن خطأ الترجمة.

التثبيت

قريبًايُفتح التثبيت من السجل مع الإطلاق. حتى ذلك الحين، هذا هو الأمر الذي ستستخدمه.

npx shadcn@latest add @ritla/icon-button

الاعتماديات التي يضيفها: @base-ui/react, @phosphor-icons/react

الاستخدام

import { MagnifyingGlassIcon } from "@phosphor-icons/react/ssr";
import { IconButton } from "@/components/ui/icon-button";

<IconButton variant="outline" icon={MagnifyingGlassIcon} label="Search" />

أمثلة

الأحجام

كل حجم مربع بارتفاع الزر من الحجم نفسه (56 و48 و40 و32 بكسل)، فيصطفان في سطر واحد. مساحة النقر تبقى 48 بكسل على الأقل في sm وxs.

الأنماط

أنماط الزر الخمسة بألوانها نفسها، والأيقونة بلون النص. isDanger يحوّل أي نمط إلى الأحمر، وinverted-ghost للأسطح الملونة.

الشكل

square (الافتراضي) يأخذ استدارة الزر في حجمه، وround دائري بالكامل للأزرار العائمة وصور الملفات الشخصية.

الحالات

loading يضع المؤشر مكان الأيقونة ويُبقي التركيز والاسم، وdisabled يوقف الزر. اضغط «حفظ»، وغيّر label أثناء التحميل («جارٍ الحفظ»).

زر الإغلاق

زر الإغلاق عند نهاية السطر، أي اليسار في العربية. الحجم xs يناسب الترويسات الكثيفة ويبقى سهل النقر.

متى تستخدم زراً بنص

زر الأيقونة للأيقونات المألوفة (تعديل، مشاركة، بحث). الإجراء الخطر يحتاج نصاً صريحاً، فاستخدم زراً بنص بدل سلة مهملات وحدها، ولا تضع زرين filled متجاورين.

مرجع الخصائص

IconButton

أي خاصية أخرى من Base UI Button تمر كما هي (onClick، type…).

الخاصية	النوع	الافتراضي	الوصف
`icon`	`IconComponent`		Change icon في Figma: أيقونة Phosphor أو كنز. الأيقونات الاتجاهية تنعكس في العربية وحدها.
`label`	`string`		مطلوب. الاسم الذي تسمعه قارئات الشاشة (`aria-label`)، بلغة الصفحة.
`shape`	`"square" \| "round"`	`"square"`	خاصية Shape: استدارة الزر أو دائرة كاملة.
`variant`	`"filled" \| "tonal" \| "outline" \| "ghost" \| "inverted-ghost"`	`"filled"`	خاصية Style، كما في الزر.
`size`	`"lg" \| "md" \| "sm" \| "xs"`	`"lg"`	خاصية Size: مربع 56 و48 و40 و32 بكسل.
`isDanger`	`boolean`	`false`	خاصية isDanger: الأحمر وحلقة تركيز حمراء.
`loading`	`boolean`	`false`	State = Loading: المؤشر مكان الأيقونة، `aria-busy`، والزر يبقى قابلاً للتركيز.
`disabled`	`boolean`	`false`	State = Disabled.
`render`	`ReactElement`		عنصر آخر بشكل زر الأيقونة، عادةً رابط. يحتفظ بدلالته ويأخذ `label` اسماً.
`className`	`string`		أصناف إضافية تُدمج عبر `cn()`.

إمكانية الوصول

لوحة المفاتيح

المفاتيح مكتوبة للاتجاه من اليسار إلى اليمين. في الاتجاه من اليمين يتبادل السهمان دورهما: السهم المتجه مع اتجاه القراءة ينقلك إلى الأمام.

المفتاح	ما يفعله
`Tab`	ينقل التركيز إلى الزر، وتظهر حلقة التركيز (حمراء مع `isDanger`).
`EnterSpace`	ينفّذ الإجراء. أثناء التحميل يبقى التركيز ولا يتكرر الإجراء.

ARIA

label مطلوب في النوع نفسه، فلا يمكن نشر زر أيقونة بلا اسم. يصبح aria-label والأيقونة aria-hidden.
اكتب الاسم بلغة الصفحة («بحث» لا «Search» في العربية)، وصف الإجراء لا الأيقونة («إغلاق» لا «علامة X»).
التحميل يضبط aria-busy="true" وaria-disabled="true" بدل disabled، فلا يضيع التركيز.
مساحة النقر 48 بكسل على الأقل في كل الأحجام (WCAG 2.5.8)، حتى حين يُرسم الزر 32 بكسل.
في أشرطة الأدوات يحتاج المستخدم المبصر تلميحاً أيضاً. سيأتي مع مكوّن Tooltip.

ملاحظات العربية والاتجاه

ينعكس

الأسهم والأسهم المثلثة تنعكس عبر <Icon>: «رجوع» بـArrowLeftIcon يشير إلى اليمين في العربية.
ترتيب الأزرار في شريط الأدوات ينعكس مع الصفحة، وزر الإغلاق يبقى عند نهاية السطر.

لا ينعكس

الزر نفسه لا ينعكس ولا يحتاج خاصية RTL؛ الأيقونة وحدها تقرر.
البحث والإشعارات والقائمة والقلب والتنزيل ومؤشر التحميل تبقى كما هي في اللغتين.

الأرقام: لا أرقام في زر الأيقونة. إن أضفت شارة عدد فوقه، نسّقها بـformatNumber لتتبع إعداد الأرقام.
الخط العربي: لا نص مرئي؛ الاسم في label. اكتبه بالعربية الطبيعية، فقارئ الشاشة ينطقه بصوت عربي حين تكون الصفحة lang="ar".
النص ثنائي الاتجاه: اسم علامة تجارية لاتيني داخل label عربي («مشاركة عبر WhatsApp») يُقرأ صحيحاً دون <bdi>، لأن aria-label نص لا يُعرض.

كل المكونات ›