Why install prompts belong in a Shadow DOM

Every third-party widget faces the same problem: your CSS collides with the host site’s CSS, and your DOM gets rewritten by whichever script loads last. Shadow DOM solves both. Here’s why InstantPWA ships every popup inside one.

The three problems Shadow DOM solves

1. Style bleed. Host * { box-sizing: border-box } or a Tailwind Preflight rewrites your padding. Inside a shadow root, host CSS doesn’t apply.
2. ID and class collisions. Your .button and their .button never meet.
3. Third-party script interference. A rogue analytics script that walks document.querySelectorAll('*') and mutates nodes stops at the shadow boundary.

The setup

const host = document.createElement('div');
host.id = 'pwa-widget-host';
document.body.appendChild(host);
const root = host.attachShadow({ mode: 'closed' });

root.innerHTML = `
  <style>
    :host { all: initial; }
    .card { font: 14px/1.4 system-ui; padding: 16px; border-radius: 12px; }
  </style>
  <div class="card">Install our app</div>
`;

:host { all: initial } is the reset that guarantees inherited properties (font, color) don’t leak in.

Event containment

Events retargeted through a closed shadow root show only the host element to outside listeners. That prevents your click handlers from being intercepted by delegated listeners on document.body.

CSP survival

Sites with strict style-src policies block external stylesheets. Attaching styles inline inside the shadow root works if the CSP allows unsafe-inline or you emit a matching nonce. We use a single <style> tag inside the root; the browser treats it as part of your script bundle.

When not to use it

Skip Shadow DOM only if you deliberately want the host site’s theme to cascade in — rare for a floating install popup, common for embedded chat widgets.