Shadow DOM Isolation

Why the widget can't break your site's styles — and how to customize it anyway.

The Problem

• Their CSS leaks into your page. A widget's global styles can override yours.
• Your CSS leaks into the widget. Your button styles can break the widget's UI.

How Threadline Solves It

The widget renders inside a Shadow DOM boundary:

• Widget CSS is scoped to its shadow root — cannot affect your page
• Your page CSS cannot penetrate the shadow boundary
• Class names are hashed (e.g., ._abc123) — no name collisions

How Customization Works

Shadow DOM blocks regular CSS selectors, but CSS custom properties pierce through. Set variables on the host element:

/* This WORKS — CSS variables cross the shadow boundary */
#threadline-comments {
  --tl-color-accent: #059669;
}

/* This DOES NOT WORK — regular selectors cannot penetrate */
#threadline-comments .comment-text {
  color: red;  /* ignored by the browser */
}

See theme customization for the full list of supported CSS variables.

Browser Support

Supported in all modern browsers (Chrome 53+, Firefox 63+, Safari 10+, Edge 79+). Internet Explorer is not supported.

Debugging

1. Open DevTools → Settings (gear icon)
2. Check "Show user agent shadow DOM" under Elements
3. The widget's shadow root will now be expandable in the Elements panel

CSS conflicts and solutions

Common host-page vs widget conflicts, and how Shadow DOM (or an iframe) resolves them.

Before: host resets break the widget

Aggressive resets on the host page can wipe button chrome if the widget shared the light DOM:

/* Host page - dangerous without isolation */
button {
  all: unset;
}

/* Without Shadow DOM, Threadline Reply / Post buttons
   lose padding, borders, and cursor styles. */

After: Shadow DOM isolation

/* Host page styles stay on the host */
button { all: unset; }

/* Widget lives in #threadline-comments shadow root.
   Host button { all: unset } does not apply inside. */

Before: host tries to restyle comments

/* Does NOT apply - selectors cannot pierce Shadow DOM */
.comment { color: red; }
#threadline-comments .comment-text { font-size: 18px; }

After: theme via --tl-* variables

/* Variables DO cross the shadow boundary */
#threadline-comments {
  --tl-color-text: #dc2626;
  --tl-font-size: 18px;
  --tl-color-accent: #059669;
}

Specificity wars

Without isolation, publishers escalate with !important and long selectors. Shadow DOM ends that fight: neither side wins by specificity, because the trees are separate. Customize only through documented --tl-* tokens on #threadline-comments.

Iframe alternative comparison