Modal
An overlay dialog that focuses the user's attention on a single task or piece of information. The page behind is blocked from interaction until the modal is dismissed.
Properties
| Name | Type | Default | Description |
|---|---|---|---|
open | boolean | false | Whether the modal is open. Controlled prop — the consumer must manage this value. |
heading | string | undefined | Heading text shown in the title bar. Used as the accessible name via aria-labelledby. |
dismissButton | boolean | true | When false, the × dismiss button is hidden. Ensure another close action is available. |
disableBackdropClick | boolean | false | When true, clicking the backdrop does not emit dismiss. Use for required confirmations. |
backdrop | 'blur' | 'shading' | 'blur' | Visual style of the backdrop. blur = frosted glass; shading = solid dark scrim. |
theme | 'dark' | 'light' | 'dark' | Per-component theme override. Reflects data-theme on the host, propagating token cascade into the shadow DOM. |
Events
| Name | Detail type | Bubbles | Description |
|---|---|---|---|
dismiss | void | No | Emitted when the user requests the modal to close — via backdrop click (unless disableBackdropClick), Escape key, or the × dismiss button. The consumer must set open={false} in response. |
Slots
| Name | Description |
|---|---|
default | Scrollable body content. Accepts any HTML, form elements, or components. |
header | Optional sub-header section rendered below the title bar (e.g. a description, metadata line). Hidden when empty. |
footer | Sticky footer section for action buttons. Rendered with a top border. Hidden when empty. |
CSS custom properties
| Property | Default | Description |
|---|---|---|
--diwa-modal-width | 560px | Width of the modal panel. Override per-instance to create narrow (confirm) or wide (data) modals. |
--diwa-modal-max-height | 85vh | Maximum height of the modal panel. The body scrolls beyond this height. |
Inherited design tokens
The following global tokens from app.css are consumed by the modal. Override them on :root or a parent element to adjust the appearance globally.
| Token | Role |
|---|---|
--diwa-bg-surface | Panel and header/footer background |
--diwa-bg-frosted | Backdrop background (blur mode) |
--diwa-bg-shading | Backdrop background (shading mode) |
--diwa-border | Panel border and internal dividers |
--diwa-shadow-xl | Panel drop shadow |
--diwa-radius-xl | Panel border radius |
--diwa-z-modal | z-index of the modal host (default: 1000) |
--diwa-blur-lg | Blur intensity of the frosted backdrop |
--diwa-border-focus | Focus ring color on the dismiss button |