RealTimeX
Sign inStart for free
RealTimeXWeb Package
IntroductionPrerequisitesInstallationProject setupQuick start
Package structureConfigurationComponentsHooksAPI integrationSocket events
OverviewReplace entire UIReplace componentsStyle with classNamesThemes & localePhone & video callingIn-call control barFeatures
Unread badgeRich-text messagesPins, stars & datesMessage threadsMentionsCanvas & draftsNotificationsAdmin permissionsServer refusalsSession & token refresh
Host app integrationTroubleshootingFAQVersion historyBest practicesSupport & contact
Web packageHelp & reference

Host app integration

CSS, modals and style isolation when the chat is installed in another project - an admin template or a custom shell.

Use this page when chat works on one page but modals look broken, popups don't appear, or you worry the package will overwrite your app's CSS.

How chat styling is isolated

LayerWhat it does
.chat-shellMain chat viewport - sidebar, message list and composer live here
.chat-theme-scopePortaled UI (modals, dropdowns, tooltips) - carries chat colours via inline CSS variables from ChatThemeProvider
--chat-* tokensChat-specific colours (--chat-surface, --chat-border, …) scoped to the shell and scope class, not your app's --primary
Tailwind utilitiesPre-compiled into styles.css at publish time - no build step or @source scan in your app

Chat does not inject global class names like .btn or .modal that would clash with Bootstrap, Ant or MUI.

Note

styles.css also declares shadcn-style fallbacks on :root (--background, --foreground, …) so Radix primitives render correctly. If your app uses the same token names, define your values after the package import, or override them on your own wrapper.

Required setup

Same as CSS setup - import the stylesheet once in your global CSS:

css
@import "@realtimexsco/live-chat/styles.css";

No @source or chat-specific config - styles.cssalready contains every class the chat's components need.

Recommended page layout

Full-screen page:

tsx
1<div className="h-dvh min-h-0 overflow-hidden">2  <ChatMain {...chatConfig} viewportHeight="screen" />3</div>

Admin shell with a fixed header (~4rem):

tsx
<ChatMain {...chatConfig} viewportHeight="calc(100dvh - 4rem)" />

Inside your own flex column:

tsx
1<div className="flex min-h-0 flex-1 overflow-hidden">2  <ChatMain {...chatConfig} viewportHeight="full" />3</div>

Why modals don't open or look wrong

SymptomUsual causeFix
Modal opens but is invisible (no backdrop, no box)styles.css not imported, or imported only on some routesImport it once in global CSS loaded on every page that renders chat
Modal seems not to openDialog renders behind the host sidebar/header (host z-index above the chat overlay)Package dialogs use z-[200]; raise chat overlays in host CSS (below) or lower the host stack
Partial styling (white box, wrong font, no radius)styles.css missing or loaded lateImport once, globally, before any route that renders chat
Works in dev, broken in prodStale file: link / local checkout not rebuiltpnpm run build in the package repo, reinstall, restart
Intermittent after a package updateStale Vite optimize cache, or linked dist/ not rebuiltStop dev server → rebuild package → reinstall → restart → hard refresh

Browser check (2 minutes)

  1. Open the modal (New chat, Forward, Attachments preview, …).
  2. DevTools → Elements → search for data-slot="dialog-content". Not in the DOM → React/state issue. In the DOM but not visible → CSS, z-index or animation issue.
  3. Computed styles on that element: no position: fixed → styles.css not imported (or stale); z-index lower than the sidebar → stacking issue; transparent background → --chat-surface / styles.css missing.

z-index with host sidebars

Chat overlays (dialogs, alert dialogs, header menus, tooltips) use z-[200]. If your shell uses a higher stack (e.g. z-[1000]), chat modals can appear hidden.

Option A - host override(safest when you can't change the shell):

css
1/* Host globals.css - after the package import */2[data-slot="dialog-overlay"],3[data-slot="dialog-content"],4[data-slot="alert-dialog-overlay"],5[data-slot="alert-dialog-content"] {6  z-index: 9999 !important;7}

Option B - customization (raise in-panel drawers only):

typescript
1export const chatClassNames = {2  drawer: "z-[9999]",3  drawerContent: "rounded-l-2xl",4};

CSS import order

css
1/* Your app base tokens first (optional) */2:root {3  --background: …;4  --foreground: …;5}6 7/* Package chat tokens + component styles */8@import "@realtimexsco/live-chat/styles.css";9 10/* Your overrides last */11:root {12  --chat-theme: #your-brand;13}

Warning

Import the package CSS once. Don't import it inside a CSS module scoped to one component - modals portal to document.body and need global utilities.

Local file: / npm link workflow

shell
1cd /path/to/realtimex-npm-package2npm run build          # required after every source change3 4cd /path/to/host-app5npm install            # refresh the file: link6# restart the host dev server

If CSS or classes look outdated, the host is almost always serving an old dist/.

Next.js reminders

  • "use client" on the chat page.
  • transpilePackages: ["@realtimexsco/live-chat"] in next.config.ts.

What the package does not require

  • Installing Lexical, DOMPurify, Radix or Zustand separately in the host app.
  • Copying chat component CSS into your repo.
  • Wrapping pages in chat-specific providers beyond <ChatMain /> (providers are internal).
PreviousSession & token refreshNextTroubleshooting

On this page

How chat styling is isolatedRequired setupRecommended page layoutWhy modals don't open or look wrongBrowser check (2 minutes)z-index with host sidebarsCSS import orderLocal file: / npm link workflowNext.js remindersWhat the package does not require
Back to top