Modal

کامپوننت Modal برای نمایش محتوایی روی صفحه‌ی اصلی استفاده می‌شود که نیاز به توجه کامل کاربر دارد؛ مثل فرم‌ها، تأیید عملیات یا نمایش جزئیات. مودال از طریق Portal روی document.body رندر می‌شود و هنگام باز بودن، اسکرول صفحه قفل می‌شود.

Import

import { Modal } from "fara-ui";

اگر هنوز FaraUI را نصب و راه‌اندازی نکرده‌ای، ابتدا صفحه‌ی شروع به کار را ببین.

Basic Usage

const [open, setOpen] = useState(false);

<Button onClick={() => setOpen(true)}>نمایش مودال</Button>
<Modal open={open} onClose={() => setOpen(false)} title="عنوان مودال">
  <p>محتوای مودال اینجاست.</p>
</Modal>;

Playground

title

children

<Modal open={open} onClose={() => setOpen(false)} title="عنوان مودال">
  محتوای مودال اینجاست.
</Modal>

Closing Behavior

مودال با هر یک از این روش‌ها بسته می‌شود:

• کلیک روی دکمه‌ی ✕ در هدر
• کلیک روی پس‌زمینه‌ی تیره (overlay)
• فشردن کلید Escape

Behavior

• قفل اسکرول: هنگام باز بودن مودال اسکرول صفحه‌ی اصلی قفل می‌شود و برای جلوگیری از پرش layout، عرض اسکرول‌بار به‌صورت خودکار جبران می‌شود.
• انیمیشن: باز و بسته شدن با انیمیشن fade/slide همراه است و المان بعد از پایان انیمیشن خروج از DOM حذف می‌شود.
• className روی پنل داخلی Modal اعمال می‌شود و برای تغییر اندازه یا ظاهر خود پنل مناسب است:

<Modal open={open} onClose={() => setOpen(false)} title="جزئیات سفارش" className="order-modal">
  {/* محتوا */}
</Modal>

Accessibility

• بستن با کلید Escape پشتیبانی می‌شود.
• دکمه‌ی بستن دارای aria-label="بستن" است.
• محدودیت شناخته‌شده: مدیریت فوکوس (focus trap) در حال حاضر پیاده‌سازی نشده است؛ برای مودال‌های حیاتی فوکوس اولیه را خودت تنظیم کن.
• پیاده‌سازی فعلی role="dialog" و aria-modal را خودکار اضافه نمی‌کند. اگر semantics کامل dialog برای محصولت لازم است، این attributeها را در wrapper مناسب اضافه کن یا کامپوننت را ارتقا بده.
• کلیک روی overlay مودال را می‌بندد؛ کلیک داخل پنل با stopPropagation از این رفتار جلوگیری می‌کند.

Data Attributes and Customize CSS

Modal hookهای پایدار زیر را تولید می‌کند:

Attribute	کاربرد
data-fara-modal-overlay	overlay تمام‌صفحه
data-open	روی overlay و پنل فقط هنگام visible بودن
data-fara-modal	پنل اصلی
data-fara-modal-header	header مودال
data-fara-modal-title	heading عنوان
data-fara-modal-close	دکمه‌ی بستن

[data-fara-modal] {
  width: min(640px, 92vw);
}

[data-fara-modal-overlay][data-open] {
  backdrop-filter: blur(3px);
}

[data-fara-modal-title] {
  margin: 0;
}

Modal با Portal در document.body رندر می‌شود؛ selectorهای آن را به container والد وابسته نکن. className فقط روی پنل است، نه overlay.

Props

Prop	Type	Default	Description
open	boolean	-	باز یا بسته بودن مودال (الزامی)
onClose	() => void	-	هنگام بسته شدن صدا زده می‌شود (الزامی)
children	ReactNode	-	محتوای مودال (الزامی)
title	string	-	عنوان هدر مودال (با پاس‌دادن آن هدر رندر می‌شود)
className	string	-	کلاس CSS اضافی روی پنل مودال