组件 · 浮层
AlertDialog
A small centered dialog that asks people to confirm an action that cannot be undone or that interrupts work, with a confirm button colored by the consequence.
也叫 ConfirmDialog, Confirmation
import { AlertDialog } from "@botiverse/raft-ui";An alert dialog asks people to confirm an action before it happens, when the action cannot be undone (delete) or interrupts work (stop, reset). It is a 400px dialog on a scrim with a title, a sentence on what will happen, Cancel and a confirm button whose color states the consequence.
When to use
| Situation | Use |
|---|---|
| An action that cannot be undone: delete a message, an agent, a server | AlertDialog, red |
| An action that interrupts but can be recovered: stop an agent, reset a session, leave a channel | AlertDialog, orange |
| An action that can be reversed in place | No dialog: do it; when a Toast offers Undo is in Feedback |
| A decision that needs more than the name typed | Dialog |
Anatomy
AlertDialog: the root. Required.AlertDialogTrigger: the button that opens it. Usually the dialog is opened from a menu item instead.AlertDialogContent: the centered surface, at most 400px wide, the width of asize="sm"Dialog, so every confirmation is one width, with the scrim (AlertDialogOverlay) behind it. Required.AlertDialogHeader: the title row, with an optionalAlertDialogClose(×).AlertDialogTitle: the title. Required.AlertDialogBodyandAlertDialogDescription: what will happen.AlertDialogFooter: the buttons, aligned to the end.AlertDialogCancel: a ghost button that closes the dialog. Required.AlertDialogAction: the confirm button. It is a Button and doesn't close the dialog by itself: close it when the action finishes.AlertDialogPortal: a lower-level part.
Variants
The confirm button's color says what happens:
| Consequence | Confirm button | Example |
|---|---|---|
| Does something | variant="primary" | Make Public |
| Interrupts, but can be recovered | variant="warning" | Stop |
| Cannot be undone | variant="danger", and a Banner with status="destructive" in the body | Delete Agent |
Deleting something large, such as an agent or a server, also asks for its name to be typed (Forms):
Behavior
- It appears and disappears without animation, over the scrim, like every centered dialog (Dialog).
- Esc and Cancel close it without acting.
Content
- Title it with the action and the thing it acts on, as a question: Delete Box?
- Say in one or two sentences what happens, in plain words: "Box leaves every channel."
- Label the confirm button with the title's verb: Stop for Stop Wug?. Keep the object when it can't be undone, on the red button: Delete Agent. Label the other button Cancel (Writing).
Accessibility
- AlertDialog wraps the Base UI Dialog and sets the
alertdialogrole, so screen readers announce it as an interruption. Base UI provides the focus trap, Esc and focus return. AlertDialogTitleis the accessible name andAlertDialogDescriptionthe description. Put the consequence inAlertDialogDescription, so it is announced with the title.- The × of
AlertDialogCloseis labeled "Close".
Rules
- Put Cancel on the left and the confirm button on the right, and no other buttons.
- Don't color the menu item that opens the dialog: the confirm button carries the color (Feedback).
API
AlertDialog
| Prop | 类型 | 默认值 |
|---|---|---|
| A ref to imperative actions. - `unmount`: Manually unmounts the dialog. Call this after any externally controlled closing animation finishes. - `close`: Closes the dialog imperatively when called. | RefObject<DialogRootActions | null> | |
| The content of the dialog. This can be a regular React node or a render function that receives the `payload` of the active trigger. | ReactNode | PayloadChildRenderFunction<unknown> | |
| Whether the dialog is initially open. | boolean | false |
| 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. | string | |
| Whether to prevent the dialog from closing on outside presses. For non-modal dialogs, this also prevents the dialog from closing when focus moves outside of it. | boolean | false |
| A handle to associate the dialog with a trigger. If specified, allows external triggers to control the dialog's open state. Can be created with the Dialog.createHandle() method. | BaseDialog.Handle<unknown> | |
| Determines if the dialog enters a modal state when open. - `true`: user interaction is limited to just the dialog: focus is trapped, document page scroll is locked, and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. - `'trap-focus'`: focus is trapped inside the dialog, but document page scroll is not locked and pointer interactions outside of it remain enabled. | boolean | "trap-focus" | true |
| Event handler called when the dialog is opened or closed. | (open: boolean, eventDetails: BaseDialog.Root.ChangeEventDetails) => void | |
| Event handler called after any animations complete when the dialog is opened or closed. | (open: boolean) => void | |
| Whether the dialog is currently open. | boolean | |
| 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). | string |
AlertDialogAction
| Prop | 类型 | 默认值 |
|---|---|---|
| boolean | ||
| string | ||
| `md` (32px) and `icon-md` for rows, cards, banners, toolbars and panel headers; `lg` and `icon-lg` (the control height) for dialog footers, forms and beside a field; `xl` for a full-width call to action. The size follows the place: see Button › Size by place. | "md" | "lg" | "xl" | "icon-md" | "icon-lg" | DeprecatedButtonSize | |
| "primary" | "accent" | "warning" | "danger" | "default" | "outline" | "information" | "muted" | "success" | "danger-secondary" | "danger-outline" | "ghost" | "on-frame" | ||
| Whether the button should be focusable when disabled. | boolean | false |
| 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>`). | boolean | true |
| Allows you to replace the component's HTML element with a different tag, or compose it with another component. | ReactElement | ((props, state) => ReactElement) |
Also takes the attributes of its element.
AlertDialogBody
接受其元素的全部属性。
AlertDialogCancel
| Prop | 类型 | 默认值 |
|---|---|---|
| `md` (32px) and `icon-md` for rows, cards, banners, toolbars and panel headers; `lg` and `icon-lg` (the control height) for dialog footers, forms and beside a field; `xl` for a full-width call to action. The size follows the place: see Button › Size by place. | "md" | "lg" | "xl" | "icon-md" | "icon-lg" | DeprecatedButtonSize | |
| "primary" | "accent" | "warning" | "danger" | "default" | "outline" | "information" | "muted" | "success" | "danger-secondary" | "danger-outline" | "ghost" | "on-frame" | ||
| 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>`). | boolean | true |
Also takes the attributes of its element.
AlertDialogClose
| Prop | 类型 | 默认值 |
|---|---|---|
| ReactNode | ||
| `md` (32px) and `icon-md` for rows, cards, banners, toolbars and panel headers; `lg` and `icon-lg` (the control height) for dialog footers, forms and beside a field; `xl` for a full-width call to action. The size follows the place: see Button › Size by place. | "md" | "lg" | "xl" | "icon-md" | "icon-lg" | DeprecatedButtonSize | |
| "primary" | "accent" | "warning" | "danger" | "default" | "outline" | "information" | "muted" | "success" | "danger-secondary" | "danger-outline" | "ghost" | "on-frame" | ||
| 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>`). | boolean | true |
Also takes the attributes of its element.
AlertDialogContent
| Prop | 类型 | 默认值 |
|---|---|---|
| false | AlertDialogOverlayProps | ||
| AlertDialogPortalProps | ||
| Determines the element to focus when the dialog is closed. | boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | HTMLElement | null | void) | |
| 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. | boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | HTMLElement | null | void) | |
| Allows you to replace the component's HTML element with a different tag, or compose it with another component. | ReactElement | ((props, state) => ReactElement) |
Also takes the attributes of its element.
AlertDialogDescription
| Prop | 类型 | 默认值 |
|---|---|---|
| Allows you to replace the component's HTML element with a different tag, or compose it with another component. | ReactElement | ((props, state) => ReactElement) |
Also takes the attributes of its element.
AlertDialogFooter, AlertDialogHeader
接受其元素的全部属性。
AlertDialogOverlay
| Prop | 类型 | 默认值 |
|---|---|---|
| Whether the backdrop is forced to render even when nested. | boolean | false |
| Allows you to replace the component's HTML element with a different tag, or compose it with another component. | ReactElement | ((props, state) => ReactElement) |
Also takes the attributes of its element.
AlertDialogPortal
| Prop | 类型 | 默认值 |
|---|---|---|
| A parent element to render the portal element into. | HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | |
| Whether to keep the portal mounted in the DOM while the popup is hidden. | boolean | false |
| Allows you to replace the component's HTML element with a different tag, or compose it with another component. | ReactElement | ((props, state) => ReactElement) |
Also takes the attributes of its element.
AlertDialogTitle
| Prop | 类型 | 默认值 |
|---|---|---|
| Allows you to replace the component's HTML element with a different tag, or compose it with another component. | ReactElement | ((props, state) => ReactElement) |
Also takes the attributes of its element.
AlertDialogTrigger
| Prop | 类型 | 默认值 |
|---|---|---|
| A handle to associate the trigger with a dialog. Can be created with the Dialog.createHandle() method. | BaseDialog.Handle<unknown> | |
| 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). | string | |
| 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>`). | boolean | true |
| A payload to pass to the dialog when it is opened. | {} | |
| Allows you to replace the component's HTML element with a different tag, or compose it with another component. | ReactElement | ((props, state) => ReactElement) |
Also takes the attributes of its element.
相关组件
改动
- 0.8.3 · FixedA
DialogorAlertDialogopened from a sheet or another dialog draws its own, lighter scrim, so it no longer sits undimmed on the surface below. A sheet opened from a dialog does the same; a sheet over a sheet is unchanged. Nesting follows the modal roots, as in Base UI, and amodal={false}parent doesn't count.