rc-dialog
Draggable, resizable wrapper for a native <dialog>, following the WAI-ARIA Dialog Modal pattern.
- Package
@rcarls/rc-dialog- Element
<rc-dialog>- Native dependency
- Requires a direct child native dialog
- State model
- Open state follows the native dialog
- Main events
rc-dialog-openrc-dialog-togglerc-dialog-request-closerc-dialog-cancelrc-dialog-close- Related
- Theme previews
Installation
- npm
- Yarn
npm install @rcarls/rc-dialog
yarn add @rcarls/rc-dialog
import '@rcarls/rc-dialog/define';
Live demo
Theming
The default demo mode shows the component without a package theme. Use the shared preview controls on this page to compare inherited, light, and dark color schemes or to apply the optional Material theme only inside the demo frames.
API
Properties
| Property | Markup | Type | Default | Description |
|---|---|---|---|---|
movable | movable | boolean | false | Allow the dialog to be moved by dragging. Use `move-handle` to restrict dragging to a specific child element (e.g. a titlebar). |
moveHandle | move-handle | string | '' | CSS selector (within the inner `<dialog>`) for the drag handle element. |
moveBounds | move-bounds | 'viewport' | 'parent' | 'viewport' | Bounds constraint for movement. |
moveStep | move-step | number | 4 | Keyboard arrow-key step in px for moving. |
resize | resize | 'none' | 'both' | 'horizontal' | 'vertical' | 'none' | Enable resizing, mirroring the CSS `resize` property values. |
resizeThreshold | resize-threshold | number | 8 | Edge hit-test thickness in px for resize detection. |
resizeStep | resize-step | number | 4 | Keyboard arrow-key step in px for resizing. |
closedBy | closed-by | 'any' | 'closerequest' | 'none' | '' | '' | Proxied to the inner `<dialog closedby="...">` attribute. Progressive enhancement, no-op in older browsers. - `'any'` — Escape OR backdrop click closes the dialog. - `'closerequest'` — Escape only (browser default for modal dialogs). - `'none'` — Only programmatic `close()` / `requestClose()`. - `''` — Attribute absent; use `light-dismiss` for JS fallback. |
lightDismiss | light-dismiss | boolean | false | When true and the dialog is modal, a click on the backdrop area calls `requestClose()`. |
modal | JS property only | boolean | true | Whether to open as modal with controlled open. Default: `true`. |
open | open | boolean | Not specified | Whether the inner `<dialog>` is currently open. Host writes update silently. |
defaultOpen | default-open | boolean | Not specified | Initial uncontrolled open state. |
returnValue | JS property only | string | Not specified | The return value set when the dialog was closed. |
Methods
| Method | Description |
|---|---|
showModal() | Opens the inner `<dialog>` as a modal and fires `rc-dialog-open`. |
show() | Opens the inner `<dialog>` (non-modal) and fires `rc-dialog-open`. |
close(returnValue?: string) | Closes the inner `<dialog>`, optionally setting a return value. |
requestClose(returnValue?: string) | Requests the inner `<dialog>` to close, firing a cancelable `cancel` event first. |
Events
| Event | Detail type | Description |
|---|---|---|
rc-dialog-open | CustomEvent | Fired when the dialog opens via `showModal()` or `show()`. |
rc-dialog-toggle | CustomEvent | Fired when user/native interaction changes open state. |
rc-dialog-request-close | No detail type documented | Fired before the dialog closes (cancellable). |
rc-dialog-cancel | No detail type documented | Mirrors the inner `<dialog>` cancel event when the close was not prevented. Backward-compatible alias for `rc-dialog-request-close`. |
rc-dialog-close | No detail type documented | Mirrors the inner `<dialog>` close event. `detail: { returnValue: string }` |
Slots
| Name | Description |
|---|---|
(default) | Place a `<dialog>` element with your content here. |
CSS Custom Properties
No CSS custom properties are documented in the custom elements manifest.
CSS Parts
No CSS parts are documented in the custom elements manifest.