Dialog
Importing
Add rh-dialog to your page with this import statement:
<script type="module">
import '@rhds/elements/rh-dialog/rh-dialog.js';
</script>To learn more about installing RHDS elements on your site using an import map read our getting started docs.
Usage
<rh-button id="first-modal-trigger">Open</rh-button>
<rh-dialog trigger="first-modal-trigger">
<h2 slot="header">Modal dialog with a header</h2>
<p>Lorem ipsum dolor sit amet, <a href="#foo">consectetur adipisicing</a> elit, sed do eiusmod tempor incididunt
ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit
anim id est laborum.</p>
<rh-cta slot="footer" href="#bar">Call to Action</rh-cta>
</rh-dialog>
<script type="module">
import '@rhds/elements/rh-button/rh-button.js';
import '@rhds/elements/rh-cta/rh-cta.js';
import '@rhds/elements/rh-dialog/rh-dialog.js';
</script>rh-dialog
Modal overlay for confirming decisions or collecting input. Traps focus and
blocks page interaction. Must have a heading or accessible-label for screen
readers. Uses native <dialog> with aria-labelledby. Escape closes the
dialog; Tab cycles focus within it. Use sparingly to avoid disrupting workflow.
Slots
| Slot Name | Summary | Description |
|---|---|---|
header
|
Dialog heading |
Should contain an h2-h6 describing the dialog's purpose. The heading becomes the accessible name via aria-labelledby. Sticks to the top when content overflows. |
description
|
Supplementary text below the heading |
Brief context supporting the header. Hidden when empty. |
[default]
|
Primary dialog content |
Accepts text, forms, images, or interactive elements. Scrolls vertically on
overflow. For video dialogs, slot a video or YouTube iframe here. |
Action buttons at the bottom of the dialog |
Primary and secondary action buttons (e.g. confirm, cancel). Hidden when empty. Focusable elements here are part of the dialog's Tab focus cycle. |
Attributes
| Attribute | DOM Property | Description | Type | Default |
|---|---|---|---|---|
variant
|
variant |
Fixed width: |
|
|
position
|
position |
Vertical placement. Set to |
|
|
accessible-label
|
accessibleLabel |
Accessible name for the dialog. Must be provided when no heading
exists in the header or default slot. Maps to |
|
|
open
|
open |
Whether the dialog is currently open. |
|
|
trigger
|
trigger |
ID of the element that opens the dialog on click. Should exist in
the same document or shadow root. Its text is used as a fallback
accessible name when no heading or |
|
|
type
|
type |
Set to |
|
|
Methods
| Method Name | Description |
|---|---|
cancel(returnValue: string)
|
Cancels and closes the dialog, dispatching a cancel event. |
setTrigger(element: HTMLElement)
|
Sets the trigger element programmatically. |
toggle()
|
Toggles the dialog open or closed. |
show()
|
Opens the dialog as a modal. |
showModal()
|
Opens the dialog as a modal. |
close(returnValue: string)
|
Closes the dialog. |
Events
| Event Name | Description |
|---|---|
open
|
Fires when the dialog opens. The event's |
close
|
Fires when the dialog closes via close button
or programmatic |
cancel
|
Fires when the user dismisses via backdrop click or Escape. No detail properties. |
CSS Shadow Parts
| Part Name | Summary | Description |
|---|---|---|
dialog
|
The dialog element |
|
|
|
The dialog's close button |
|
content
|
The container for the dialog content |
|
header
|
The container for the optional dialog header |
|
description
|
The container for the optional dialog description in the header |
|
body
|
The container for the dialog body content |
|
|
|
Actions footer container |
CSS Custom Properties
| CSS Property | Description | Default |
|---|---|---|
--rh-dialog-close-button-color |
Close button icon color; in video mode defaults to lightest surface token for contrast against the dark backdrop. |
var(--rh-color-surface-lightest, #ffffff)
|
--rh-dialog-video-aspect-ratio |
Video dialog aspect ratio. Defaults to 16/9. Override for non-standard video dimensions (e.g. 4/3 or 21/9). |
16/9
|
Design Tokens
| Token | Description | Copy |
|---|---|---|
--rh-color-surface-darker
|
Secondary surface (dark theme) |
|
--rh-font-family-body-text
|
Dialog typeface Body text font family |
|
--rh-box-shadow-xl
|
Dialog box-shadow Extra large box shadow |
|
--rh-color-text-primary
|
Dialog text color |
|
--rh-space-3xl
|
Header and body inline-end padding for close button clearance 48px spacer |
|
--rh-font-family-heading
|
Heading typeface Heading font family |
|
--rh-font-size-heading-sm
|
Heading text size h5 heading font size |
|
--rh-font-weight-body-text-regular
|
Heading font weight Regular font weight |
|
--rh-space-lg
|
Header bottom margin Header pseudo-element height for sticky overlap 16px spacer |
|
--rh-space-xl
|
Dialog inner padding Last body paragraph bottom margin 24px spacer |
|
--rh-color-icon-secondary
|
Default close button icon color |
|
--rh-color-surface-dark
|
Tertiary surface (dark theme) |
|
--rh-border-radius-default
|
Dialog box corner rounding Close button corner rounding 3px border radius; Example: Card |
|
--rh-length-xl
|
Close button hit area height Close button hit area width 24px length token |
|
--rh-space-2xl
|
Dialog box inner padding at wide viewports 32px spacer |
|
--rh-color-gray-90
|
Secondary surface (dark theme) |
|
--rh-opacity-60
|
60% opacity |
|
--rh-space-md
|
Footer action button gap 8px spacer |
|
--rh-space-sm
|
6px spacer |
|
--rh-color-surface-lightest
|
Primary surface (light theme) |
|
Other libraries
To learn more about our other libraries, visit this page.
Feedback
To give feedback about anything on this page, contact us.
