Modal
Display a modal dialog box with a distinct accessible title, optional description, content area, and actions.
When to use
When requiring users to interact with the application, but without jumping to a new page and interrupting the user's workflow, you can use Modal to create a new floating layer over the current page to get user feedback or display information.
Additionally, if you need to show a simple confirmation dialog, you can use App.useApp hooks.
Use description for explanatory copy below the title. Do not place a subtitle inside title:
assistive technology must receive a concise accessible name and a separate description. Focus
returns to the opening control even when a controlled consumer unmounts the Modal immediately.
The positioning wrapper and backdrop expose cb-modal and cb-modal__backdrop respectively.
Use the upstream classNames semantic slots for any other additive styling.
Stacking
Most dialogs stay on the default --cb-z-modal rung. A dialog rendered by Drawer content
automatically moves to the documented above-drawer rung, with its backdrop; pass
layer="above-drawer" only to control an exceptional call chain deliberately. Popups the
dialog itself opens — date pickers, selects, dropdowns — inherit the rung through Ant's own
zIndex, so they resolve above the dialog rather than wedging underneath it. This is the
only supported nested overlay: a modal inside another modal, or a drawer inside a dialog,
still belongs on its own page.
Keyboard
TabandShift+Tabmove through focusable controls inside the modal.Escaperequests dismissal when keyboard dismissal is enabled.- After dismissal, focus returns to the control that opened the modal unless
focusable.focusTriggerAfterCloseis explicitly disabled.
Do / don't
- Do pass a short
titleand supportingdescriptionas separate props. - Don't build a stacked title-and-subtitle React node and pass the whole block as
title. - Do pass
layer="above-drawer"only to control an exceptional overlay call chain deliberately. - Don't open a modal inside another modal, or a drawer inside a dialog, to work around stacking.
Examples
API
Modal, Modal.confirm, and Modal.useModal are exported from @ceebee/ui/client.
Modal
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
afterClose | Specify a function that will be called when modal is closed completely | function | - | — |
cancelButtonProps | The cancel button props | ButtonProps | - | — |
cancelText | Text of the Cancel button | ReactNode | Cancel | — |
centered | Centered Modal | boolean | false | — |
classNames | Customize class for each semantic structure inside the Modal component. Supports object or function. | Record<SemanticDOM, string> | (info: { props }) => Record<SemanticDOM, string> | - | — |
closable | Whether a close (x) button is visible on top right or not | boolean | ClosableType | true | - |
closeIcon | Custom close icon. 5.7.0: close button will be hidden when setting to null or false | ReactNode | <CloseOutlined /> | — |
confirmLoading | Whether to apply loading visual effect for OK button or not | boolean | false | — |
destroyOnClose | Whether to unmount child components on onClose | boolean | false | — |
destroyOnHidden | Whether to unmount child components on onClose | boolean | false | 5.25.0 |
focusTriggerAfterClose | Whether need to focus trigger element after dialog is closed. Please use focusable.focusTriggerAfterClose instead | boolean | true | 4.9.0 |
footer | Footer content, set as footer={null} when you don't need default buttons | ReactNode | (originNode: ReactNode, extra: { OkBtn: React.FC, CancelBtn: React.FC }) => ReactNode | (OK and Cancel buttons) | renderFunction: 5.9.0 |
forceRender | Force render Modal | boolean | false | — |
focusable | Configuration for focus management in the Modal | { trap?: boolean, focusTriggerAfterClose?: boolean } | - | 6.2.0 |
getContainer | The mounted node for Modal but still display at fullscreen | HTMLElement | () => HTMLElement | Selectors | false | document.body | — |
keyboard | Whether support press esc to close | boolean | true | — |
mask | Mask effect | boolean | {enabled?: boolean, blur?: boolean, closable?: boolean} | true | mask.closable: 6.3.0 |
maskClosable | Whether to close the modal dialog when the mask (area outside the modal) is clicked. Please use mask.closable instead. | boolean | true | - |
modalRender | Custom modal content render | (node: ReactNode) => ReactNode | - | 4.7.0 |
okButtonProps | The ok button props | ButtonProps | - | — |
okText | Text of the OK button | ReactNode | OK | — |
okType | Button type of the OK button | string | primary | — |
style | Style of floating layer, typically used at least for adjusting the position | CSSProperties | - | — |
styles | Customize inline style for each semantic structure inside the Modal component. Supports object or function. | Record<SemanticDOM, CSSProperties> | (info: { props })=> Record<SemanticDOM, CSSProperties> | - | — |
loading | Show the skeleton | boolean | — | 5.18.0 |
scrollLock | Whether to lock body scroll when modal opens | boolean | true | 6.5.0 |
title | The modal dialog's title | ReactNode | - | — |
open | Whether the modal dialog is visible or not | boolean | false | — |
width | Width of the modal dialog | string | number | Breakpoint | 520 | Breakpoint: 5.23.0 |
wrapClassName | The class name of the container of the modal dialog | string | - | — |
zIndex | The z-index of the Modal | number | 1000 | — |
onCancel | Specify a function that will be called when a user clicks mask, close button on top right or Cancel button | function(e) | - | — |
onOk | Specify a function that will be called when a user clicks the OK button | function(e) | - | — |
afterOpenChange | Callback when the animation ends when Modal is turned on and off | (open: boolean) => void | - | 5.4.0 |
ClosableType
| Property | Description | Type | Default | Version |
|---|---|---|---|---|
afterClose | Specify a function that will be called when modal is closed completely | function | - | - |
closeIcon | Custom close icon | ReactNode | undefined | - |
disabled | Whether disabled close icon | boolean | false | - |
onClose | Trigger when modal close | Function | undefined | - |