Choosing a Theme

Your Synaptiq widget's theme controls the overall look and feel visitors experience when they interact with your sales chat. A well-matched theme builds trust, reinforces brand identity, and keeps the conversation interface feeling native to your site.

All theme settings live under Admin Dashboard > Settings > Widget > Appearance.

Built-In Themes

Synaptiq ships with three built-in themes you can activate with a single click.

Light Theme

The default. White backgrounds, dark text, and a clean card-style chat window. Works well on marketing sites, SaaS landing pages, and any page with a light color scheme.

| Element | Value | |---|---| | Background | #FFFFFF | | Text | #1A1A2E | | Chat bubble (agent) | #F3F4F6 | | Chat bubble (visitor) | Primary color fill |

Dark Theme

Inverted palette optimized for sites with dark backgrounds or for users who prefer reduced brightness. Text is light, surfaces are dark gray, and accent colors remain vivid.

| Element | Value | |---|---| | Background | #1E1E2E | | Text | #E2E8F0 | | Chat bubble (agent) | #2D2D3F | | Chat bubble (visitor) | Primary color fill |

Auto Theme

Follows the visitor's operating system preference using prefers-color-scheme. When a visitor switches between light and dark mode at the OS level, the widget updates in real time without a page reload.

<!-- The embed script respects auto theme by default -->
<script
  src="https://synaptiqintel.com/widget.js"
  data-synaptiq-id="YOUR_WORKSPACE_ID"
  data-theme="auto"
></script>

To set Auto via the dashboard, select Auto (match system) from the Theme dropdown. This is recommended for most deployments because it respects visitor preferences without any extra work.

Customizing Colors

Beyond the three presets, you can override individual color values to match your brand exactly.

Primary Color

The primary color is applied to:

• The chat bubble trigger button background
• Visitor message bubbles
• Links and interactive elements inside the chat window
• The header bar gradient (when gradient mode is on)

Set it in Settings > Widget > Appearance > Primary Color by entering a hex value or using the color picker.

<!-- Override via embed attribute -->
<script
  src="https://synaptiqintel.com/widget.js"
  data-synaptiq-id="YOUR_WORKSPACE_ID"
  data-primary-color="#6C63FF"
></script>

Background Color

Controls the chat window body background. When using a custom background color, make sure your text color provides enough contrast. Synaptiq will display a warning in the preview panel if the contrast ratio falls below WCAG AA (4.5:1).

Text Color

Sets the default text color for agent messages, timestamps, and UI labels. Visitor messages always use white text on the primary color background.

Header Color

By default the header inherits the primary color. You can decouple it by toggling Use custom header color and selecting a separate value. This is useful when your brand has a secondary accent you want to feature at the top of the chat window.

Real-Time Preview

Every color change is reflected instantly in the live preview panel on the right side of the Appearance settings page. The preview renders a mock conversation so you can evaluate:

• Chat bubble contrast -- are visitor and agent messages easy to distinguish?
• Header readability -- is the title text legible against the header background?
• Bubble button visibility -- does the floating trigger stand out on the page?
• Link styling -- are hyperlinks inside messages clearly clickable?

Use the Toggle background button at the bottom of the preview to switch between a simulated light page and a dark page so you can verify the widget looks correct in both contexts.

How Themes Affect Widget Elements

Chat Bubble (Trigger)

The floating button that visitors click to open the chat window. It takes the primary color as its background and renders the chat icon in white. In dark theme, it adds a subtle box-shadow glow so the bubble remains visible against dark pages.

Header Bar

Displays your workspace name and the online/away status indicator. In light theme it uses a solid primary color background. In dark theme it uses a slightly darkened variant to reduce glare.

Message Bubbles

Agent messages use a neutral surface color (light gray in light theme, dark gray in dark theme). Visitor messages always use the primary color fill with white text. This consistent asymmetry makes it immediately clear who said what.

Input Area

The text input field at the bottom of the chat window inherits the main background color with a 1px border in a muted shade. The send button uses the primary color.

Gradient Headers

Enable gradient mode under Appearance > Header Style > Gradient to blend your primary color into a secondary color across the header bar. You can control the gradient angle (default is 135 degrees) and the secondary color.

<script
  src="https://synaptiqintel.com/widget.js"
  data-synaptiq-id="YOUR_WORKSPACE_ID"
  data-header-gradient="true"
  data-header-gradient-from="#6C63FF"
  data-header-gradient-to="#48BEFF"
  data-header-gradient-angle="135"
></script>

Gradients only apply to the header bar. The trigger button continues to use the solid primary color so it remains visually distinct and recognizable across pages.

Theme Switching via JavaScript

If your site includes a manual dark/light mode toggle, you can sync the widget theme with it using the Synaptiq JavaScript API:

// Call this whenever your site's theme changes
function syncWidgetTheme(isDark) {
  window.Synaptiq.setTheme(isDark ? "dark" : "light");
}

The setTheme method accepts "light", "dark", or "auto". Changes apply instantly without reloading the widget.

Troubleshooting

• Widget loads with the wrong theme: Verify that no data-theme attribute on the embed script is overriding the dashboard setting. Embed attributes take priority.
• Colors look different in production vs. preview: The preview uses an isolated iframe. If your site applies global CSS filters or color adjustments to the <html> element, those can shift how the widget appears in production.
• Dark theme text is hard to read: Check that your custom text color has sufficient contrast against the dark background. Use the WebAIM contrast checker to verify a 4.5:1 minimum ratio.

Applying Theme via the Embed Script

You can lock a theme at the embed level so dashboard changes do not override it. This is useful if you deploy the widget across multiple domains with different visual requirements.

<script
  src="https://synaptiqintel.com/widget.js"
  data-synaptiq-id="YOUR_WORKSPACE_ID"
  data-theme="dark"
  data-primary-color="#FF6B6B"
  data-bg-color="#121212"
  data-text-color="#F0F0F0"
></script>

When both dashboard settings and embed attributes are present, embed attributes take priority. This lets your development team enforce design consistency regardless of what a non-technical admin might change in the dashboard.

Tips for Choosing the Right Theme

1. Match your site's existing palette. Pull your brand's primary hex from your style guide and use it as the widget primary color.
2. Use Auto theme when possible. It respects visitor preferences and eliminates a whole class of readability complaints.
3. Test on mobile. Open the preview on a phone-sized viewport -- colors that look muted on a desktop monitor can appear more saturated on OLED screens.
4. Keep contrast high. If your primary color is very light (yellow, light green), consider using a darker header color so the title text remains readable.
5. Save and verify. After saving, open your production site in an incognito window to confirm the widget loads with the correct theme. Browser caching can sometimes delay updates by a few minutes.

Next Steps

Once your theme is set, continue to Customizing the Chat Icon to configure the trigger button's icon, shape, and animation.