Embedding a third-party widget into a plain static site is easy. But modern apps are SPAs (single-page applications) with their own routing, global styles and component lifecycle, and that's exactly where third-party widgets start to conflict: the layout breaks, styles leak both ways, the widget disappears on navigation or gets duplicated on every re-render. This article is a practical breakdown of how to embed a chat widget in a SPA cleanly: no CSS conflicts, no memory leaks, and no surprises when navigating between pages.
The problem isn't specific to any one framework — it applies equally to React, Vue, Angular or Svelte. The root cause is always the same: the app and the widget live in the same DOM tree and compete for the same CSS classes and lifecycle. Let's look at where the conflicts come from and how a widget's architecture can eliminate them before you write a single line of integration code.
The problem: leaking styles
The main integration headache is mutual style leakage. Your app's global rules (say, a box-sizing reset or styles for all buttons) affect the widget, and the widget's styles can touch your page. The result is a "drifting" layout on both sides that's hard to debug.
Picture a typical CSS reset at the top level of your app:
button {
border: none;
background: transparent;
font-family: inherit;
}
This rule is perfectly reasonable for your app — but if the chat widget is mounted as a plain <div> with its own buttons, it falls under this rule too. The "Send" button in the chat suddenly loses its background and border, and you spend hours looking for the cause because the widget's own CSS file looks correct.
The symmetric problem happens the other way too: if the widget ships its own global reset.css or targets body or * directly, it can unpredictably change how your app looks. CSS specificity and file load order turn into a lottery.
The classic workarounds are class namespacing like .widget-xyz-button or CSS Modules with randomized hashes in class names. They work, but only if both the app and the widget follow the convention consistently, and no future developer breaks it. That's a fragile agreement, not a guarantee.
The solution: Shadow DOM
Shadow DOM creates an isolated DOM subtree with its own style boundary. Everything inside the "shadow" doesn't see the page's global styles, and the page doesn't see the widget's styles. For an embeddable chat this is almost the ideal solution: the widget looks the same on any site regardless of its CSS, and breaks nothing.
const host = document.createElement('div');
document.body.appendChild(host);
const shadow = host.attachShadow({ mode: 'open' });
shadow.innerHTML = `<style>/* widget styles */</style><div id="chat-root"></div>`;
This is a simplified example, but the idea holds: host is a regular element on the page, while everything inside shadow lives by its own CSS rules. No button { border: none } rule from your app can reach in there.
Why not an iframe
An iframe also isolates styles — even more strongly, since it's a separate document with a separate JS context. But that isolation costs something: passing data between the page and the widget needs postMessage, resizing to fit content is trickier, and initialization is slower due to a separate HTTP request for the whole document. Shadow DOM is a compromise: CSS isolation, while JS and the DOM stay in the same context, so passing user context or listening to events is simpler.
One nuance worth remembering: CSS custom properties (--variable) and inherited properties like font-family or color cross the Shadow DOM boundary by default. That's convenient if you want the widget to pick up the site's font, but it can surprise you if you expected full isolation. On choosing between iframe, script and Shadow DOM in the broader context, see the article on adding chat to a website.
SPA routing and component lifecycle
On a static site, every page transition is a full reload, and the widget simply re-initializes on every page. In a SPA it's different: the router swaps the page's content without a reload, and components mount and unmount dozens of times over a user's session.
That creates a specific trap: if the widget's container is mounted inside a component tied to a specific route (say, a Layout for one section of the site), navigating away unmounts that component — and the widget disappears with it.
The right approach is to mount the widget's container outside the app's render tree, directly into document.body, once for the lifetime of the tab. In React that means not making <Widget /> part of the page's JSX tree, but initializing the loader script once at the app's root level (say, in a useEffect in the top-level component with an empty dependency array) and leaving it alone after that.
Another nuance: React 18+'s StrictMode deliberately mounts effects twice in development to catch cleanup issues. If the widget's initialization isn't idempotent, you'll end up with two widgets on the page in dev mode. The simplest guard is a flag on window that ensures the loader runs only once:
if (!window.__widgetLoaded) {
window.__widgetLoaded = true;
loadWidgetLoader();
}
Passing user context
In a SPA you usually already know who your user is. It would be a shame not to use that: pass the name, email and, say, plan into the widget — and the operator immediately sees who they're talking to, without extra questions. Technically it's just a call to a widget method with a context object after initialization.
// illustrative example
widget.setUser({
name: user.name,
email: user.email,
plan: user.plan,
});
The key is to update the context when the user signs in or out. If you passed the context once on the first page load, and then the user logs in without a reload (typical SPA behavior), the widget will keep treating them as anonymous until you explicitly update the data again.
It's worth drawing a boundary here too: don't pass anything sensitive into the context — passwords, access tokens, payment details. Context exists so the operator understands who they're talking to and maybe which plan they're on, not to mirror your entire user database into the chat.
Lazy initialization in a SPA
- Load a loader, not the whole widget. First a tiny script (usually a few kilobytes); the heavy part — UI, styles, chat logic — is pulled in asynchronously, only when the user actually opens the chat window. That means the widget's presence on the page barely affects metrics like LCP or TTI.
- Initialize after the app mounts, so you don't compete for resources with the first render. In a SPA, the first few seconds after load are the most expensive: the browser parses and executes the app bundle, hydrates components, fetches data. A simple trick is deferring loader initialization until the
loadevent, or even until the first idle period (requestIdleCallback), if the browser supports it. - Don't re-initialize on every navigation. A SPA's routing is client-side — the widget should survive a page change, not be recreated. This ties back to the lifecycle point above: if you wire up the loader inside every page component instead of the app's root, you risk loading and mounting the widget again on every transition.
Common mistakes when integrating with a SPA
- Mounting the container inside a component tied to a specific route — after navigating away, the widget disappears along with the unmounted component.
- No guard against double initialization — especially noticeable in React 18
StrictModeor during hot module reloading (HMR) in development. - User context passed only once on page load instead of being updated on sign-in or sign-out — the operator sees stale or missing data.
- Testing the integration only in dev mode. A production build often has different CSS minification rules and script load order — a conflict that didn't show up locally can appear only in production.
- Ignoring z-index and
overflow: hiddenon parent containers. Shadow DOM isolates styles, but not the page's stacking context — if the widget is mounted inside an element withoverflow: hidden, its popup can get clipped even when the styles themselves don't conflict.
Checklist: how to embed a chat widget in a SPA without conflicts
In short: to embed a chat widget in a SPA without style conflicts or navigation surprises, check five things.
- The widget uses Shadow DOM or an iframe — not raw styles in the shared DOM.
- The loader initializes once, at the app's root level, not inside an individual page component.
- The widget's container is mounted directly into
document.body, outside the router's render tree. - User context is updated on every auth change, not just on first load.
- The integration is verified against the production build, not only in dev mode.
How it's done in Duck Float
The Duck Float widget is built for these requirements from the start: it runs on Shadow DOM, so it doesn't conflict with a SPA's styles; installs with one line of code via a lightweight loader with lazy loading; and accepts user context — name, email, plan. Requests from the widget land in the same inbox as the Telegram bot and the API, and AI prepares a draft reply in the customer's language — the operator just presses Tab, edits it, or writes their own. Duck Float is free during the beta; want to try it or have a technical question — message us through the widget on this site.
