Theming

The widget’s look is controlled by one JSON object, a WidgetThemeConfig. You pick a light or dark base and override only what you need; everything you leave out comes from the base. The same object works in the dashboard, in the script tag and in code.

new CallersWebSdk.WebCall({
  token,
  theme: {
    base: 'light',
    fab: { backgroundColor: '#0f766e', text: 'Ask us anything' },
    answers: { button: { background: '#0f766e', radius: 'full' } },
  },
});

Prefer building themes visually? The dashboard has a theme builder, and the theme you save on the agent applies to every installation automatically. See Styling the widget.

Which theme wins

A theme passed in code: theme in the config, data-theme on the script tag, or a later setTheme() call.
The theme saved on the agent in the dashboard, fetched when the widget loads.
Default Light.

So you can set the theme once on the agent, and override it in code only on sites that need something different. Once you pass a theme in code (or call setTheme()), the dashboard theme no longer applies to that instance. The launcher label follows its own order: fabText in the config, then the theme’s fab.text, then an icon-only button.

Set a theme

<script src="https://cdn.callers.ai/sdk.js" data-agent="YOUR_AGENT_ID" data-theme="dark"></script>

<script
  src="https://cdn.callers.ai/sdk.js"
  data-agent="YOUR_AGENT_ID"
  data-theme='{"base":"dark","fab":{"backgroundColor":"#1930a3"}}'
></script>

const { WebCall, DEFAULT_DARK_THEME } = window.CallersWebSdk;

new WebCall({
  token,
  theme: { ...DEFAULT_DARK_THEME, fab: { backgroundColor: '#1930a3' } },
});

DEFAULT_LIGHT_THEME and DEFAULT_DARK_THEME are the exported starting points ({ base: 'light', name: 'Default Light' } and { base: 'dark', name: 'Default Dark' }).

The widget's pre-call card rendered with the Default Light and Default Dark themes — The two base palettes on the pre-call card. Every override in your theme sits on top of one of them.

Change the theme at runtime

setTheme() replaces the whole theme immediately, even mid-call. Values you leave out go back to the base palette, so pass the complete theme each time.

const brand = { fab: { backgroundColor: '#0f766e' } };

matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (event) => {
  webCall.setTheme({ base: event.matches ? 'dark' : 'light', ...brand });
});

Launcher position

Position is set outside the theme, so it also works on top of the dashboard theme:

new WebCall({ token, launcherPosition: 'bottom-left', launcherOffset: 32 });

<script src="https://cdn.callers.ai/sdk.js" data-agent="YOUR_AGENT_ID"
  data-launcher-position="top-right" data-launcher-offset="16"></script>

Option	Values	Default
`launcherPosition` / `data-launcher-position`	`bottom-right`, `bottom-left`, `top-right`, `top-left`	`bottom-right`
`launcherOffset` / `data-launcher-offset`	0–200 px from both edges	`24`

Two page mockups with the Talk to us launcher in the bottom-right and top-left corners — The launcher in the default corner and in the top-left corner. The call window opens from the same corner.

The call window opens from the same corner. To place the call UI inside your layout instead, use containerId (see Configuration).

`WidgetThemeConfig` reference

Every field except base is optional. Colors accept any CSS color: hex, rgb(), rgba() or a named color.

Top level

'light' | 'dark'

required

The palette everything else layers onto.

string

A label for your own reference.

string

default:"Inter"

Inter, system (the device’s UI font), or any font family your page already loads.

Launcher: `fab`

Field	Type	Description
`fab.backgroundColor`	color	Round button background (the icon badge on a labeled launcher)
`fab.iconColor`	color	Phone icon color
`fab.text`	string	Launcher label. Empty for an icon-only button.
`fab.collapsedBackground`	color	Background of the labeled pill
`fab.textColor`	color	Label color

Call window: `sections`

Field	Description
`sections.header.background`, `.text`, `.icon`, `.border`	The header bar
`sections.chat.background`	The conversation area
`sections.bottom.background`, `.border`	The composer bar
`sections.precall.ctaButtonBackground`, `.ctaButtonText`	The Voice Call button on the pre-call card
`sections.precall.frostBackground`	The frosted close button
`sections.precall.connectingBackground`	The connecting indicator
`sections.precall.finishedBackground`	The divider shown after a call ends

The hang-up button always stays red.

Agent side: `questions`

Field	Type	Default
`questions.titles.fontSize`	`sm` \| `md` \| `lg`	`md`
`questions.titles.align`	`left` \| `center`	`left`
`questions.titles.color`, `.secondaryColor`	color	from base
`questions.agentBubble.background`, `.text`, `.border`	color	from base
`questions.agentBubble.fontSize`	`sm` \| `md` \| `lg`	`md`
`questions.agentBubble.align`	`left` \| `center`	`left`

Visitor side: `answers`

Field	Type	Default
`answers.input.variant`	`filled` \| `outline`	`filled`
`answers.input.radius`	`sm` \| `md` \| `lg` \| `full`	`md`
`answers.button.background`, `.text`	color	from base
`answers.button.radius`	`sm` \| `md` \| `lg` \| `full`	`full`
`answers.selectors.selected`, `.unselected`, `.indicator`	color	from base
`answers.selectors.size`	`sm` \| `md` \| `lg`	`md`
`answers.selectors.align`	`left` \| `center`	`left`
`answers.userBubble.background`, `.text`, `.border`	color	from base
`answers.userBubble.fontSize`, `.align`	as above	`md`, `left`
`answers.widgetCard.background`, `.text`, `.border`	color	Outer card of forms shown inline in the transcript
`answers.widgetCard.radius`	`sm` \| `md` \| `lg` \| `full`	`lg`
`answers.widgetCard.elevation`	`none` \| `sm` \| `md` \| `lg`	`md`
`answers.card.background`, `.border`, `.radius`, `.elevation`	Cards inside designed (A2UI) forms	radius `md`, elevation `none`
`answers.row.gap`	`sm` \| `md` \| `lg`: spacing between items in designed forms	`md`

answers.widgetCard applies only to forms shown as an inline card. Forms shown inside an agent message use questions.agentBubble colors.

Scale values

Keyword	Titles	Body text	Radius	Row gap
`sm`	16px	14px	8px	8px
`md`	18px	16px	16px	12px
`lg`	20px	20px	24px	16px
`full`			fully rounded

Base palettes

Token	Light	Dark
Background	`#ffffff`	`#1a1a2e`
Text	`#181b19`	`#eeeeee`
Muted text	`#707b73`	`#9aa0a6`
Primary (buttons, launcher)	`#3655e8`	`#3655e8`

Complete example

{
  "base": "dark",
  "name": "Brand Dark",
  "font": { "family": "Inter" },
  "fab": {
    "backgroundColor": "#1930a3",
    "iconColor": "#ffffff",
    "text": "Talk to us",
    "collapsedBackground": "#1a1a2e",
    "textColor": "#eeeeee"
  },
  "sections": {
    "header": { "background": "#16213e", "text": "#eeeeee" },
    "chat": { "background": "#1a1a2e" },
    "bottom": { "background": "#16213e", "border": "#2a2a3e" },
    "precall": { "ctaButtonBackground": "#1930a3", "ctaButtonText": "#ffffff" }
  },
  "questions": {
    "titles": { "color": "#ffffff", "fontSize": "md" },
    "agentBubble": { "background": "#22223a", "text": "#eeeeee" }
  },
  "answers": {
    "input": { "variant": "filled", "radius": "md" },
    "button": { "background": "#1930a3", "text": "#ffffff", "radius": "full" },
    "userBubble": { "background": "#1930a3", "text": "#ffffff" }
  }
}

Try in the playground

Turn on Custom widget theme in the Look step to edit colors live, then open Get code > setTheme() to copy the result.

Dark widget

Start from the dark base.

Teal brand, bottom left

A labeled launcher with custom brand colors.

Styling the widget

Build a theme visually in the dashboard.

Configuration

Every option, in code and as script tag attributes.

Playground

Try themes live and copy the generated code.

Talking avatars

Add an animated avatar to the widget.

Get started

Features

Reference

Advanced

Which theme wins

Set a theme

Change the theme at runtime

Launcher position

`WidgetThemeConfig` reference

Top level

Launcher: `fab`

Call window: `sections`

Agent side: `questions`

Visitor side: `answers`

Scale values

Base palettes

Complete example

Try in the playground

Dark widget

Teal brand, bottom left

Styling the widget

Configuration

Playground

Talking avatars

​Which theme wins

​Set a theme

​Change the theme at runtime

​Launcher position

​WidgetThemeConfig reference

​Top level

​Launcher: fab

​Call window: sections

​Agent side: questions

​Visitor side: answers

​Scale values

​Base palettes

​Complete example

​Try in the playground

Dark widget

Teal brand, bottom left

​Related

Styling the widget

Configuration

Playground

Talking avatars

Which theme wins

Set a theme

Change the theme at runtime

Launcher position

`WidgetThemeConfig` reference

Top level

Launcher: `fab`

Call window: `sections`

Agent side: `questions`

Visitor side: `answers`

Scale values

Base palettes

Complete example

Try in the playground

Related