Dialog — wd-dialog

Category: Overlay · Tag: wd-dialogBack to: Components overview

---

What it does

A modal dialog: a centered panel over a full-screen backdrop (the shader). It is invisible when the page loads — nothing shows until your own code opens it by calling its toggleDialog() method. Use it for confirmations, announcements, forms, cookie/consent prompts, and anything else that should interrupt the page.

---

Adding it & its settings

Add Component → Overlay → Dialog.

Basic Settings (all components): #id, Classes, Inline Style. Give the dialog an #id — you'll need it to open the dialog from a button (see Triggering it).

Component Settings:

Setting	What it does
Disable closing	When checked, clicking the backdrop or pressing Esc does nothing — the dialog can only be closed from your own code (e.g. a button inside it that calls toggleDialog()). Use it when the visitor must make a choice.
Scroll behavior	The dialog never grows taller than the page height minus 2rem. This picks where the scrollbar appears when the content is taller than that: Scroll the dialog body (default — the header and footer stay pinned while the middle scrolls) or Scroll the entire dialog (the whole panel scrolls as one, header and footer included).

---

Content & slots

The dialog has three slots:

• dialog-header (named) — rendered pinned at the top, with a bottom border. Only appears if you slot something into it.
• default slot — everything without a slot attribute becomes the dialog body.
• dialog-footer (named) — rendered pinned at the bottom, laid out as a right-aligned row (for buttons). Only appears if you slot something into it.

<wd-dialog id="newsletter-dialog">
  <h3 slot="dialog-header">Stay in the loop</h3>

  <p>Join our newsletter and never miss an update.</p>

  <div slot="dialog-footer">
    <button onclick="document.querySelector('#newsletter-dialog').toggleDialog()">Maybe later</button>
    <button class="primary">Subscribe</button>
  </div>
</wd-dialog>

A dialog with no header/footer content renders as a plain panel — the named sections don't leave empty bars behind.

---

Triggering it

The dialog does nothing on its own — open (and close) it by calling its toggleDialog() method, typically from a button's onclick event:

document.querySelector('#newsletter-dialog').toggleDialog()

• Each call toggles: closed → open, open → closed.
• While open, the page behind can't scroll (the dialog restores the page's scroll when it closes).
• The visitor can close it by clicking the backdrop or pressing Esc — unless Disable closing is checked. toggleDialog() from your own code always works, regardless of that setting.
• It emits a dialogToggled event (detail.state: 1 opened, 0 closed) if you need to react to it.

---

Styling

CSS variables

Shader (the backdrop)

Variable	Default
--wd-dialog-shader-background	rgba(0, 0, 0, 0.5)
--wd-dialog-shader-blur	0px (backdrop blur radius)
--wd-dialog-shader-z-index	999

Dialog panel

Variable	Default
--wd-dialog-background	#fff
--wd-dialog-border-radius	1rem
--wd-dialog-box-shadow	0 2px 10px rgba(0,0,0,0.1)
--wd-dialog-z-index	999
--wd-dialog-width	auto
--wd-dialog-max-width	90%
--wd-dialog-max-height	calc(100vh - 2rem)
--wd-dialog-gap	1rem (space between header/body/footer)
--wd-dialog-padding	0

Header

Variable	Default
--wd-dialog-header-padding	1rem
--wd-dialog-header-border-bottom	1px solid #eee
--wd-dialog-header-font-size	1.25rem
--wd-dialog-header-font-weight	bold
--wd-dialog-header-color	#333

Body

Variable	Default
--wd-dialog-body-padding	1rem
--wd-dialog-body-font-size	1rem
--wd-dialog-body-color	#555

Footer

Variable	Default
--wd-dialog-footer-padding	1rem
--wd-dialog-footer-border-top	1px solid #eee
--wd-dialog-footer-gap	0.5rem

/* example: a frosted, wider dialog */
wd-dialog {
  --wd-dialog-shader-blur: 6px;
  --wd-dialog-width: 560px;
  --wd-dialog-border-radius: 0.5rem;
}

::part()

Part	Element
dialog-<id>	The dialog wrapper (shader + panel).

wd-dialog::part(dialog-newsletter) { font-family: inherit; }

---

Notes

• Invisible by default is the point — don't look for a "show on load" setting; call toggleDialog() when you want it open (e.g. on a button click, or from a page script after a delay).
• One #id per dialog. A page can hold several dialogs; target each by its own id in querySelector.
• Disable closing never blocks your own code — it only disables the backdrop click and Esc for the visitor.