DEV Community

Michael Yousrie
Michael Yousrie

Posted on

How to embed a widget on any site without CSS collisions (Shadow DOM)

#webdev #javascript #webcomponents #css

If you have ever dropped a third-party widget onto a page and watched it either inherit the host site's CSS or quietly break the host's own layout, you have run into the oldest problem in embeddable widgets: the DOM is shared, so styles leak in both directions.

The host page has a global a { color: red } and suddenly every link in your widget is red. Your widget ships a .button class and now the host's own buttons look wrong. Iframes solve isolation but bring their own pain: fixed sizing, awkward communication, and they feel heavy for something as small as a "what's new" panel.

There is a better tool built into every modern browser: the Shadow DOM.

What the Shadow DOM actually does

A shadow root is a separate DOM tree attached to a host element. Styles defined inside it do not leak out, and styles from the outer page do not leak in. It is the same mechanism the browser uses internally for elements like <video> and <input type="range">, where you can see the control but not style its internals.

Here is the whole idea in a few lines:

// 1. Put a host element on the page
const host = document.createElement('div');
host.id = 'changelog-widget';
document.body.appendChild(host);

// 2. Attach a shadow root to it
const shadow = host.attachShadow({ mode: 'open' });

// 3. Everything you render inside is isolated
shadow.innerHTML = `
  <style>
    .panel {
      font: 14px/1.5 system-ui, sans-serif;
      color: #111;
      background: #fff;
      padding: 16px;
      border-radius: 8px;
    }
    a { color: #2563eb; }
  </style>
  <div class="panel">
    <strong>What's new</strong>
    <p>We just shipped dark mode.</p>
    <a href="#">See all updates</a>
  </div>
`;
Enter fullscreen mode Exit fullscreen mode

That a { color: #2563eb } rule only applies inside the shadow root. The host page's global link color cannot reach it, and your .panel class will never collide with a .panel on the host site. No prefixing, no BEM gymnastics, no !important wars.

The boundary is not a wall for everything

A few things cross the shadow boundary on purpose, and knowing which ones saves you hours:

  • CSS custom properties inherit through. If the host page sets --brand-color, you can read var(--brand-color) inside the shadow root. This is the clean way to let a host theme your widget without exposing your internals.
  • Fonts loaded on the page are usable inside. @font-face and font files loaded by the host are available, so your widget can match the site if you want it to.
  • Events retarget. A click inside the shadow tree still bubbles to the host, but event.target is rewritten to the host element so you do not leak your internal structure.
  • :host styles the host element itself, which is handy for positioning the whole widget from inside. 
:host {
  position: fixed;
  bottom: 24px;
  right: 24px;
  z-index: 2147483000;
}
Enter fullscreen mode Exit fullscreen mode

Open vs closed

attachShadow({ mode: 'open' }) lets outside JavaScript reach the tree via host.shadowRoot. mode: 'closed' returns null there. Closed feels safer but mostly just makes debugging harder for you without stopping a determined host page, so open is the pragmatic default for a widget.

Why this matters for embeddable products

The reason this technique is worth reaching for is distribution. If your widget is fully isolated, your install instructions collapse to a single line:

<script src="https://cdn.example.com/widget.js" async></script>
Enter fullscreen mode Exit fullscreen mode

The script creates its host element, attaches a shadow root, and renders. It works the same on a React app, a Rails site, a WordPress theme, or a hand-written HTML page, because it never touches the host's styles and the host never touches its own.

This is exactly how I built the changelog widget for Patchlog. It is a drop-in "what's new" widget for SaaS products: one script tag, rendered inside a Shadow DOM so it never collides with the host site's CSS, with light, dark, and auto theming that reads the host's CSS variables when you want it to. There is a free tier if you want to see the technique in a shipped product rather than a blog snippet.

Takeaways

  • Reach for the Shadow DOM when you need real style isolation without the weight of an iframe.
  • Remember the intentional exceptions: CSS variables, fonts, events, and :host.
  • Use mode: 'open' unless you have a specific reason not to.

Style isolation used to be the hardest part of shipping an embeddable widget. The platform quietly solved it years ago, and most of us just have not switched over yet.

Top comments (0)