Custom CSS Overrides

The dashboard settings cover the most common visual adjustments, but sometimes you need pixel-level control. Synaptiq exposes a set of CSS custom properties and well-defined class selectors that you can override to achieve exactly the design you want.

The Custom CSS Field

Navigate to Admin Dashboard > Settings > Widget > Appearance > Custom CSS. This textarea accepts raw CSS that gets injected inside the widget's shadow DOM. Because the widget renders in an iframe with a shadow root, your site's global styles do not leak in -- and vice versa. The Custom CSS field is the supported way to inject styles into that boundary.

Paste your CSS, click Save, and the preview panel updates immediately. The CSS is stored alongside your workspace configuration and loaded each time the widget initializes.

Character Limit

The Custom CSS field accepts up to 10,000 characters. If you need more than that, consider hosting your CSS externally and referencing it via the embed attribute:

<script
  src="https://synaptiqintel.com/widget.js"
  data-synaptiq-id="YOUR_WORKSPACE_ID"
  data-custom-css-url="https://yoursite.com/styles/synaptiq-overrides.css"
></script>

The external file is fetched once on widget initialization and cached for the session.

CSS Custom Properties Reference

Synaptiq defines a comprehensive set of custom properties on the widget's root element. Override any of these to change the corresponding visual.

:root {
  /* Primary brand color -- buttons, visitor bubbles, links */
  --synaptiq-primary: #6C63FF;
  --synaptiq-primary-rgb: 108, 99, 255;     /* RGB components for alpha usage */
  --synaptiq-primary-hover: #5A52E0;        /* Hover state for primary elements */

  /* Backgrounds */
  --synaptiq-bg: #FFFFFF;                    /* Chat window body */
  --synaptiq-bg-secondary: #F9FAFB;         /* Input area, divider rows */
  --synaptiq-bg-header: var(--synaptiq-primary); /* Header bar */

  /* Text */
  --synaptiq-text: #1A1A2E;                 /* Default body text */
  --synaptiq-text-secondary: #6B7280;       /* Timestamps, meta labels */
  --synaptiq-text-on-primary: #FFFFFF;      /* Text on primary-colored surfaces */

  /* Message bubbles */
  --synaptiq-bubble-agent: #F3F4F6;
  --synaptiq-bubble-agent-text: #1A1A2E;
  --synaptiq-bubble-visitor: var(--synaptiq-primary);
  --synaptiq-bubble-visitor-text: #FFFFFF;

  /* Borders, shadows */
  --synaptiq-border: #E5E7EB;
  --synaptiq-border-focus: var(--synaptiq-primary);
  --synaptiq-shadow: 0 8px 32px rgba(0, 0, 0, 0.12);
  --synaptiq-shadow-trigger: 0 4px 16px rgba(0, 0, 0, 0.16);

  /* Layout */
  --synaptiq-window-width: 400px;
  --synaptiq-window-height: 600px;
  --synaptiq-trigger-size: 60px;
  --synaptiq-window-radius: 16px;
  --synaptiq-bubble-radius: 12px;
  --synaptiq-trigger-radius: 50%;

  /* Typography */
  --synaptiq-font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
  --synaptiq-font-size: 14px;
  --synaptiq-font-size-small: 12px;
  --synaptiq-line-height: 1.5;
}

Targeting Specific Widget Elements

Beyond custom properties, you can target individual elements using Synaptiq's stable CSS class names. These classes are part of the public API and will not change across minor versions.

Key Selectors

| Selector | Element | |---|---| | .synaptiq-trigger | The floating trigger button | | .synaptiq-window | The chat window container | | .synaptiq-header | The header bar | | .synaptiq-header__title | Workspace name text in header | | .synaptiq-header__status | Online/away indicator | | .synaptiq-messages | The scrollable message list | | .synaptiq-bubble | Any message bubble | | .synaptiq-bubble--agent | Agent message bubble | | .synaptiq-bubble--visitor | Visitor message bubble | | .synaptiq-input | The text input container | | .synaptiq-input__field | The actual textarea element | | .synaptiq-input__send | The send button | | .synaptiq-badge | Notification badge on trigger | | .synaptiq-typing | Typing indicator dots | | .synaptiq-footer | "Powered by Synaptiq" footer |

Practical Examples

Custom Font

Load a Google Font and apply it to the entire widget:

@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap');

:root {
  --synaptiq-font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
}

If your site already loads Inter, the widget will reuse the cached font files -- no duplicate download.

Rounded Bubble Style

Give message bubbles a more rounded, pill-like shape:

:root {
  --synaptiq-bubble-radius: 20px;
}

/* Flatten the corner closest to the sender's avatar */
.synaptiq-bubble--agent {
  border-bottom-left-radius: 4px;
}

.synaptiq-bubble--visitor {
  border-bottom-right-radius: 4px;
}

Shadow Customization

Replace the default shadow with a softer version, or remove it entirely:

/* Softer, more diffused shadow */
:root {
  --synaptiq-shadow: 0 4px 24px rgba(0, 0, 0, 0.06),
                     0 1px 4px rgba(0, 0, 0, 0.04);
  --synaptiq-shadow-trigger: 0 2px 8px rgba(0, 0, 0, 0.1);
}

/* Or remove shadows completely */
:root {
  --synaptiq-shadow: none;
  --synaptiq-shadow-trigger: none;
}

Entrance Animation

Add a slide-up entrance when the chat window opens:

@keyframes synaptiq-slide-up {
  from { opacity: 0; transform: translateY(16px) scale(0.96); }
  to   { opacity: 1; transform: translateY(0) scale(1); }
}

.synaptiq-window {
  animation: synaptiq-slide-up 0.25s ease-out;
}

Compact Mode

Reduce padding and font sizes for an information-dense layout:

:root {
  --synaptiq-font-size: 13px;
  --synaptiq-font-size-small: 11px;
  --synaptiq-line-height: 1.4;
}

.synaptiq-bubble { padding: 8px 12px; }
.synaptiq-messages { gap: 6px; }
.synaptiq-header { padding: 10px 14px; }

Hiding the Powered-By Footer

Enterprise plan customers can remove the "Powered by Synaptiq" footer via Settings > Widget > Branding, or with CSS:

.synaptiq-footer {
  display: none;
}

This only works if your plan includes white-label branding. On other plans, the footer re-renders even if hidden via CSS.

Debugging Your Custom CSS

1. Use the preview panel. Every change in the Custom CSS field renders instantly in the dashboard preview. Iterate there before saving.
2. Inspect the shadow DOM. In Chrome DevTools, open the Elements panel, find the #synaptiq-widget-container element, expand its shadow root, and inspect elements directly. You can test CSS changes in the Styles panel before committing them to the dashboard field.
3. Check specificity. If a style is not applying, it may be overridden by a more specific internal selector. Add the element class to your rule to increase specificity. Avoid !important unless strictly necessary.
4. Test both themes. If your widget uses Auto theme, test your custom CSS in both light and dark mode. Use the prefers-color-scheme media query to write conditional overrides:

@media (prefers-color-scheme: dark) {
  :root {
    --synaptiq-bubble-agent: #2A2A3C;
    --synaptiq-border: #3A3A4C;
  }
}

5. Validate on mobile. Open the preview in responsive mode. Some CSS properties (especially fixed widths and absolute positioning) behave differently on small screens.

Precedence Rules

When multiple sources define the same property, Synaptiq resolves them in this order (highest priority first):

1. Custom CSS field / external CSS file -- your overrides always win.
2. Embed data-* attributes -- values set on the script tag.
3. Dashboard settings -- values configured in the admin panel.
4. Theme defaults -- the built-in light/dark/auto values.

This means your Custom CSS overrides everything else, giving you full control when you need it.

Next Steps

You now have complete control over your Synaptiq widget's appearance. For behavioral configuration -- proactive messages, operating hours, and conversation routing -- see the AI Configuration section.