> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AlertDialog

> اطلب التأكيد قبل إجراء يتطلب قرارًا صريحًا.

## نظرة عامة

استخدم `AlertDialog` لقرار يقطع سير العمل الحالي، مثل تأكيد الحذف. يوفّر دلالات `alertdialog`، وإدارة التركيز، وتأكيدًا أو إلغاءً صريحًا.

هذا المكوّن الأساسي مخصّص لواجهات Twenty UI المستقلة والواجهات التي يملكها المضيف. يجب على مكوّنات الواجهة طلب تأكيد عبر [واجهة برمجة تطبيقات مربع حوار المضيف SDK](https://docs.twenty.com/ar/developers/extend/apps/layout/front-components.md#host-communication-api). يُحظر استخدام `Dialog` و`AlertDialog` ومربعات حوار المتصفح الأصلية مباشرةً داخل عارض المكوّن الأمامي.

**Light**

[مثال AlertDialog (light)](https://storybook.twenty.com/iframe.html?id=ui-surfaces-alertdialog--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[مثال AlertDialog (dark)](https://storybook.twenty.com/iframe.html?id=ui-surfaces-alertdialog--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-surfaces-alertdialog--display)

## استخدام

### حالة غير متحكم بها

استخدم `defaultOpen` لتعيين مستوى الظهور الأولي. يتولى مربع الحوار التغييرات اللاحقة من المشغّل وعناصر التحكم في الإغلاق وتفاعلات الرفض.

```tsx theme={null}
import { Button } from 'twenty-ui/primitives/input';
import { AlertDialog } from 'twenty-ui/primitives/surfaces';

type DeleteConfirmationProps = { onDelete: () => void };

export const DeleteConfirmation = ({ onDelete }: DeleteConfirmationProps) => (
  <AlertDialog.Root defaultOpen={false}>
    <AlertDialog.Trigger
      render={<Button variant="solid">Delete record</Button>}
    />
    <AlertDialog.Portal>
      <AlertDialog.Backdrop />
      <AlertDialog.Viewport>
        <AlertDialog.Popup>
          <AlertDialog.Header>
            <AlertDialog.Title>Delete this record?</AlertDialog.Title>
            <AlertDialog.Description>
              This record will be permanently deleted. This action cannot be
              undone.
            </AlertDialog.Description>
          </AlertDialog.Header>
          <AlertDialog.Footer>
            <AlertDialog.Close render={<Button>Cancel</Button>} />
            <AlertDialog.Close
              onClick={onDelete}
              render={<Button color="danger">Delete</Button>}
            />
          </AlertDialog.Footer>
        </AlertDialog.Popup>
      </AlertDialog.Viewport>
    </AlertDialog.Portal>
  </AlertDialog.Root>
);
```

القيمة الافتراضية لـ `defaultOpen` هي `false`، لذا يمكن حذفه. يستخدم هذا المثال دالة رد اتصال تأكيد متزامنة ويُغلق بعد تنفيذ الإجراء.

## البنية التشريحية

أبقِ الأجزاء ذات الصلة داخل `AlertDialog.Root`، أو صِل المشغّلات المنفصلة عبر مقبض. أنشئ البوابة والخلفية ومنفذ العرض والنافذة المنبثقة بصورة منفصلة.

```text theme={null}
AlertDialog.Root
├── AlertDialog.Trigger
└── AlertDialog.Portal
    ├── AlertDialog.Backdrop
    └── AlertDialog.Viewport
        └── AlertDialog.Popup
            ├── AlertDialog.Header
            │   ├── AlertDialog.Title
            │   └── AlertDialog.Description
            ├── AlertDialog.Body
            └── AlertDialog.Footer
                ├── AlertDialog.Close
                └── Confirmation action
```

| الجزء | المتطلبة | الغرض |
| - | - | - |
| `Root` | مطلوب | ينسق حالة الفتح وسلوك النافذة المشروطة. |
| `المشغّل` | اختياري لمربع حوار يُفتح برمجيًا | يفتح مربع الحوار ويوفر هدفًا لإعادة التركيز. |
| `Portal` | مُوصى به | ينقل التراكب إلى حاويته ويتحكم في تركيبه. |
| `Backdrop` | اختياري | يفصل التنبيه بصريًا عن الصفحة المحيطة. |
| `Viewport` | مُوصى به | يحدّد موضع النافذة المنبثقة ويوفر المنطقة المحيطة القابلة للتمرير الخاصة بها. |
| `Popup` | مطلوب | يعرض محتوى التنبيه مع إدارة التركيز. |
| `العنوان` | مُوصى به | يوفّر الاسم المرئي للتنبيه. الاسم المتاح مطلوب دائمًا. |
| `Description` | موصى به للتأكيد | يشرح القرار وعواقبه. |
| `Header`، `Body`، `Footer` | أجزاء تخطيط اختيارية | رتّب العناوين والمحتوى الإضافي والإجراءات. |
| `إغلاق` | موصى به للإلغاء | يوفر إجراء إغلاق صريحًا. |

عيّن `container` و`keepMounted` على `Portal`، وسمات الخلفية على `Backdrop`، وسمات التخطيط على `Viewport`، وخصائص `size` والتركيز على `Popup`. يقبل كل جزء من العنصر سماته الأصلية ومعالجاته ومرجعه وتركيب `render` الخاص به. يشير `Popup.ref` إلى عنصر محتوى التنبيه. ينشئ `Title` و`Description` العلاقات المتاحة؛ وفّر `aria-label` على `Popup` عند حذف العنوان.

إجراء التأكيد هو محتوى للتطبيق، وليس جزءًا مُصدّرًا. استخدم `Close` مع معالج متزامن أو `Button` مع حالة فتح خاضعة للتحكم للتأكيد غير المتزامن.

## حالة متحكم بها

مرر `open` وحدّثه باستخدام `onOpenChange` للتحكم في ظهور مربع الحوار نفسه ضمن حالة React. تتلقى دالة الاستدعاء القيمة المنطقية المطلوبة وتفاصيل الحدث المصدر، بما في ذلك `reason` و`event` و`cancel()`. استدعِ `eventDetails.cancel()` لرفض تغيير مطلوب. يُشغَّل `onOpenChangeComplete` بعد انتهاء انتقالات الفتح أو الإغلاق.

```tsx theme={null}
import { useState } from 'react';
import { Button } from 'twenty-ui/primitives/input';
import { AlertDialog } from 'twenty-ui/primitives/surfaces';

type DeleteConfirmationProps = { onDelete: () => void };

export const DeleteConfirmation = ({ onDelete }: DeleteConfirmationProps) => {
  const [open, setOpen] = useState(false);

  return (
    <AlertDialog.Root open={open} onOpenChange={setOpen}>
      <AlertDialog.Trigger
        render={<Button variant="solid">Delete record</Button>}
      />
      <AlertDialog.Portal>
        <AlertDialog.Backdrop />
        <AlertDialog.Viewport>
          <AlertDialog.Popup>
            <AlertDialog.Header>
              <AlertDialog.Title>Delete this record?</AlertDialog.Title>
              <AlertDialog.Description>
                This record will be permanently deleted. This action cannot be
                undone.
              </AlertDialog.Description>
            </AlertDialog.Header>
            <AlertDialog.Footer>
              <AlertDialog.Close render={<Button>Cancel</Button>} />
              <AlertDialog.Close
                onClick={onDelete}
                render={<Button color="danger">Delete</Button>}
              />
            </AlertDialog.Footer>
          </AlertDialog.Popup>
        </AlertDialog.Viewport>
      </AlertDialog.Portal>
    </AlertDialog.Root>
  );
};
```

للتأكيد غير المتزامن، استخدم `Button` مع معالج الإجراء بدلاً من `AlertDialog.Close`. أبقِ `open` بالقيمة true أثناء انتظار الإجراء، واستدعِ `setOpen(false)` بعد نجاحه، واعرض خطأً داخل مربع الحوار إذا فشل.

## التركيب باستخدام الأزرار

استخدم `render` لمنح عناصر التحكم في التشغيل والإغلاق تنسيق أزرار Twenty UI. توفر أجزاء مربع الحوار معالجات التفاعل وrefs الخاصة بها للأزرار.

```tsx theme={null}
import { Button } from 'twenty-ui/primitives/input';
import { AlertDialog } from 'twenty-ui/primitives/surfaces';

type DeleteConfirmationProps = { onDelete: () => void };

export const DeleteConfirmation = ({ onDelete }: DeleteConfirmationProps) => (
  <AlertDialog.Root>
    <AlertDialog.Trigger
      render={<Button variant="solid">Delete record</Button>}
    />
    <AlertDialog.Portal>
      <AlertDialog.Backdrop />
      <AlertDialog.Viewport>
        <AlertDialog.Popup>
          <AlertDialog.Header>
            <AlertDialog.Title>Delete this record?</AlertDialog.Title>
            <AlertDialog.Description>
              This record will be permanently deleted. This action cannot be
              undone.
            </AlertDialog.Description>
          </AlertDialog.Header>
          <AlertDialog.Footer>
            <AlertDialog.Close render={<Button>Cancel</Button>} />
            <AlertDialog.Close
              onClick={onDelete}
              render={<Button color="danger">Delete</Button>}
            />
          </AlertDialog.Footer>
        </AlertDialog.Popup>
      </AlertDialog.Viewport>
    </AlertDialog.Portal>
  </AlertDialog.Root>
);
```

أبقِ كل إجراء كعنصر تحكم تفاعلي واحد. إذا غلّفت `Button` في مكوّنك الخاص، [مرّر props وref المقدّمين](https://docs.twenty.com/ar/ui/primitives/overview#custom-components).

## المشغّلات المنفصلة والإجراءات الحتمية

أنشئ مقبضًا مرة واحدة باستخدام `AlertDialog.createHandle\<Payload>()` ومرّره إلى `handle` على `Root` وكل `Trigger` منفصل. تكون `payload` المكتوبة للمشغّل متاحة لدالة عرض الطفل الخاصة بالجذر. يدعم المقبض أيضًا `open(triggerId)` و`openWithPayload(payload)` و`close()` والخاصية الجالبة `isOpen` أثناء تركيب جذره. مرّر معرّف مشغّل مطابقًا إلى `open`، أو `null` للفتح دون مشغّل. استدعِ الأساليب الحتمية من معالجات الأحداث أو التأثيرات.

يكشف `Root.actionsRef` عن `close()` و`unmount()`. للحصول على حركة إغلاق متحكَّم بها خارجيًا، استدعِ `eventDetails.preventUnmountOnClose()` في `onOpenChange`، ثم استدعِ `actionsRef.current?.unmount()` بعد انتهاء الحركة. تدير الأجزاء المنسقة العادية انتقالاتها الخاصة دون هذه الإجراءات الحتمية.

## التحجيم والبوابات

يقبل `Popup.size` القيم `sm` و`md` و`lg` و`xl` و`fullscreen`، وتكون قيمته الافتراضية `md`. ينتمي الحجم والمظهر إلى سطح AlertDialog ولا يلزم أن يطابقا إعدادات Dialog المسبقة.

تكون القيمة الافتراضية لـ `Portal.container` هي حاوية البوابة لأقرب سمة. من دون واحدة، يستخدم Base UI وجهة البوابة الافتراضية الخاصة به، وهي عادةً `document.body`. يتجاوز عنصر صريح أو جذر ظل أو مرجع تلك الوجهة. يؤجّل `null` صريح التركيب إلى أن تصبح الحاوية متاحة. يعالج Base UI مرجعًا تكون `current` فيه `null` باستخدام وجهته الافتراضية؛ استخدم `container={null}` عندما يجب أن ينتظر التركيب.

يحتفظ المحتوى المُمرَّر عبر البوابة بسياق السمة. يرث `Portal` و`Viewport` اتجاه النص المقدَّم ما لم تعيّن `dir` صراحةً. عيّن `Portal.keepMounted` للاحتفاظ بالمحتوى المركّب وحالة النموذج أثناء الإغلاق.

## التركيز والإغلاق

يحصر التنبيه التركيز، ويحظر التفاعل الخارجي، ويقفل تمرير الصفحة أثناء الفتح. يطلب مفتاح Escape الإغلاق؛ أما النقر خارجًا فلا يفعل ذلك. لمنع الإغلاق بمفتاح Escape، ألغِ تغيير `escape-key` في `onOpenChange`. وفّر دائمًا إجراءً مرئيًا للإلغاء أو الإغلاق.

افتراضيًا، ينتقل التركيز إلى أول عنصر تحكم قابل للتبويب، أو إلى النافذة المنبثقة عند الفتح باللمس. ضع الإجراء الأقل تدميرًا أولًا، أو استخدم `Popup.initialFocus` لتحديده. يعود التركيز إلى المشغّل أو العنصر الذي كان عليه التركيز سابقًا عند إغلاق التنبيه. استخدم `Popup.finalFocus` عندما يزيل إجراء ناجح ذلك الهدف. تقبل كلتا خاصيتي التركيز قيمة منطقية أو مرجع عنصر أو دالة استدعاء لنوع التفاعل وفقًا للعقد المصدر.

## الإزاحة

يُنشأ المرجع من أنواع المكونات العامة. تُقبل أيضًا السمات الأصلية، بما في ذلك الأسماء المتاحة ومعالجات الأحداث، في الأجزاء التي تعرض عناصر.

### AlertDialog.Root

**Root.actionsRef** `RefObject\<DialogRootActions | null\>`

A ref to imperative actions.

* `unmount`: Ends the closing phase of the alert dialog after an externally controlled closing animation finishes.
  Call `preventUnmountOnClose()` in `onOpenChange` first, otherwise the alert dialog completes closing on its own.
  Whether it leaves the DOM is decided by `keepMounted` on the portal.
* `close`: Closes the alert dialog imperatively when called.

**Root.children** `ReactNode | PayloadChildRenderFunction\<Payload\>`

The content of the dialog.
This can be a regular React node or a render function that receives the `payload` of the active trigger.

**Root.defaultOpen** `boolean` (default: false)

Whether the dialog is initially open.

To render a controlled dialog, use the `open` prop instead.

**Root.defaultTriggerId** `string | null`

ID of the trigger that the dialog is associated with.
This is useful in conjunction with the `defaultOpen` prop to create an initially open dialog.

**Root.handle** `AlertDialogHandle\<Payload\>`

A handle to associate the alert dialog with a trigger.
If specified, allows external triggers to control the alert dialog's open state.
Can be created with the AlertDialog.createHandle() method.

**Root.onOpenChange** `((open: boolean, eventDetails: AlertDialogRootChangeEventDetails) =\> void)`

Event handler called when the alert dialog is opened or closed.

**Root.onOpenChangeComplete** `((open: boolean) =\> void)`

Event handler called after any animations complete when the dialog is opened or closed.

**Root.open** `boolean`

Whether the dialog is currently open.

**Root.triggerId** `string | null`

ID of the trigger that the dialog is associated with.
This is useful in conjunction with the `open` prop to create a controlled dialog.
There's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set).

### AlertDialog.Trigger

**Trigger.className** `string | ((state: DialogTriggerState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Trigger.handle** `AlertDialogHandle\<Payload\>`

A handle to associate the trigger with an alert dialog.
Can be created with the AlertDialog.createHandle() method.

**Trigger.id** `string`

ID of the trigger. In addition to being forwarded to the rendered element,
it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot `triggerId` prop).

**Trigger.nativeButton** `boolean` (default: true)

Whether the component renders a native `<button>` element when replacing it
via the `render` prop.
Set to `false` if the rendered element is not a button (for example, `<div>`).

**Trigger.payload** `Payload`

A payload to pass to the dialog when it is opened.

**Trigger.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, DialogTriggerState\>`

Allows you to replace the component's HTML element
with a different tag, or compose it with another component.

Accepts a `ReactElement` or a function that returns the element to render.

**Trigger.style** `CSSProperties | ((state: DialogTriggerState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### AlertDialog.Portal

**Portal.className** `string | ((state: DialogPortalState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Portal.container** `HTMLElement | ShadowRoot | RefObject\<HTMLElement | ShadowRoot | null\> | null`

Portal destination. Omission uses the theme container or Base UI default; explicit `null` defers mounting. A ref with a null current value uses the Base UI default destination.

**Portal.keepMounted** `boolean` (default: false)

Keeps content mounted while the alert is closed.

**Portal.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, DialogPortalState\>`

Allows you to replace the component's HTML element
with a different tag, or compose it with another component.

Accepts a `ReactElement` or a function that returns the element to render.

**Portal.style** `CSSProperties | ((state: DialogPortalState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### AlertDialog.Backdrop

**Backdrop.className** `string | ((state: DialogBackdropState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Backdrop.forceRender** `boolean` (default: false)

Whether the backdrop is forced to render even when nested.

**Backdrop.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, DialogBackdropState\>`

Allows you to replace the component's HTML element
with a different tag, or compose it with another component.

Accepts a `ReactElement` or a function that returns the element to render.

**Backdrop.style** `CSSProperties | ((state: DialogBackdropState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### AlertDialog.Viewport

**Viewport.className** `string | ((state: DialogViewportState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Viewport.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, DialogViewportState\>`

Allows you to replace the component's HTML element
with a different tag, or compose it with another component.

Accepts a `ReactElement` or a function that returns the element to render.

**Viewport.style** `CSSProperties | ((state: DialogViewportState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### AlertDialog.Popup

**Popup.className** `string | ((state: DialogPopupState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Popup.finalFocus** `boolean | RefObject\<HTMLElement | null\> | ((closeType: InteractionType) =\> boolean | void | HTMLElement | null)`

Determines the element to focus when the dialog is closed.

* `false`: Do not move focus.
* `true`: Move focus based on the default behavior (trigger or previously focused element).
* `RefObject`: Move focus to the ref element.
* `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).
  Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.

**Popup.initialFocus** `boolean | RefObject\<HTMLElement | null\> | ((openType: InteractionType) =\> boolean | void | HTMLElement | null)`

Determines the element to focus when the dialog is opened.
By default, focus moves to the first tabbable element inside the popup, except when the dialog
is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.

* `false`: Do not move focus.
* `true`: Move focus based on the default behavior (first tabbable element or popup).
* `RefObject`: Move focus to the ref element.
* `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).
  Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.

**Popup.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, DialogPopupState\>`

Allows you to replace the component's HTML element
with a different tag, or compose it with another component.

Accepts a `ReactElement` or a function that returns the element to render.

**Popup.size** `"fullscreen" | "lg" | "md" | "sm" | "xl"` (default: md)

Width of the alert, or `fullscreen` to fill the viewport.

**Popup.style** `CSSProperties | ((state: DialogPopupState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### AlertDialog.Title

**Title.className** `string | ((state: DialogTitleState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Title.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, DialogTitleState\>`

Allows you to replace the component's HTML element
with a different tag, or compose it with another component.

Accepts a `ReactElement` or a function that returns the element to render.

**Title.style** `CSSProperties | ((state: DialogTitleState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### AlertDialog.Description

**Description.className** `string | ((state: DialogDescriptionState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Description.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, DialogDescriptionState\>`

Allows you to replace the component's HTML element
with a different tag, or compose it with another component.

Accepts a `ReactElement` or a function that returns the element to render.

**Description.style** `CSSProperties | ((state: DialogDescriptionState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### AlertDialog.Close

**Close.className** `string | ((state: DialogCloseState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Close.nativeButton** `boolean` (default: true)

Whether the component renders a native `<button>` element when replacing it
via the `render` prop.
Set to `false` if the rendered element is not a button (for example, `<div>`).

**Close.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, DialogCloseState\>`

Allows you to replace the component's HTML element
with a different tag, or compose it with another component.

Accepts a `ReactElement` or a function that returns the element to render.

**Close.style** `CSSProperties | ((state: DialogCloseState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### AlertDialog.Header

**Header.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, \{\}\>`

Allows you to replace the component's HTML element
with a different tag, or compose it with another component.

Accepts a `ReactElement` or a function that returns the element to render.

### AlertDialog.Body

**Body.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, \{\}\>`

Allows you to replace the component's HTML element
with a different tag, or compose it with another component.

Accepts a `ReactElement` or a function that returns the element to render.

### AlertDialog.Footer

**Footer.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, \{\}\>`

Allows you to replace the component's HTML element
with a different tag, or compose it with another component.

Accepts a `ReactElement` or a function that returns the element to render.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.