Skip to main content

Widget Styles & Appearance

Audience: Sales · Support · QA · Engineering · Management · Where in app: Settings → Widget → Colors and Style tabs · Plan availability: All plans

Almost everything a visitor sees on the widget is tunable from the dashboard: message bubble colors, button colors, header/footer, the call screen background, the launcher copy, and the questions asked before chat starts. Settings live mostly on companies.widget_design plus several top-level and per-style color objects. Changes take effect on the next visitor session — no redeploy.

What it does​

  • Sets the color palette for messages, buttons, header, footer, and call screen.
  • Provides per-launcher-style palettes (smart, ultimate/extended, pill, welcome, bubble).
  • Controls visitor-facing copy (launcher headings, button labels).
  • Defines the pre-chat questions (online and offline) and contact-info questions.
  • Configures the whitelabel "Powered by" footer.

How it works​

The admin edits colors and copy in the Colors and Style tabs; values are saved onto the company document and fetched by the widget at load. A live mini-preview in the dashboard renders changes as you type.

Core color schema (companies.widget_design)​

The modern schema is nested (see WidgetDesign in types/company.ts):

GroupFields
message.receiverbackground_color, text_color (visitor's bubble)
message.senderbackground_color, text_color (agent / AI bubble)
headerbackground_color, text_color
footerbackground_color, text_color, hide_knock_logo, hide_powered_by
btn_video_call / btn_audio_call / btn_chatbackground_color, text_color
btn_down_arrowbackground_color, text_color, arrow_position
btn_submit_phonebackground_color, text_color
sticky_widgetbackground_color, icon_and_text_color
call_backgroundbackground_color, background_image
live_tagbackground_color, text_color, enabled
bubble_widgetbackground_color, text_color

An older flat schema (receiver_message_bg, sender_message_bg, button_bg, header_bg, footer_bg, call_background_color, chatbot_auto_trigger_bg, etc.) is referenced in legacy material. The modern bundle uses the nested form above; expect both shapes in the wild depending on the company's age and which codebase serves it.

Per-launcher-style palettes​

Each launcher style has its own optional color object so styles can be themed independently:

StyleObjectNotable fields
Smartsmart_widget_colorsbackground_color, text_color
Ultimate (extended)extended_widget_colorsvideo_btn_color/_icon, audio_btn_color/_icon, chat_btn_color/_icon, booking_btn_color/_icon, icon_and_text_color, live_tag_bg, live_tag_text
Chat Pillpill_widget_colorsgradient_start, gradient_end, text_color
Welcomewelcome_widget_colorspill_gradient_start/_end, pill_text_color, chat_btn_color/_icon, call_btn_color/_icon, schedule_btn_color/_icon/_label, show_schedule_btn, close_btn_color, close_btn_icon, icon_and_text_color, footer_background, footer_text_color
Bubblebubble_widgetbackground_color, text_color
Retro IMretro_skin, retro_custom_colorsPreset skin name or custom + primary/text — see Retro IM skins

Retro IM skins​

companies.retro_skin enum: blue (default) | olive | silver | bubblegum (classic) | midnight | lagoon | sunset (modern — a3b8ca7, extra modern palette in retroIcons.ts SKINS, flatter window styling) | custom (c934275ee). custom reads companies.retro_custom_colors { primary (default #0B5CD9), text (default #FFFFFF) } and derives the rest of the palette (title-bar gradient, frame, panel, line, accent, toolbar) by mixing the primary toward white/black — customSkin() in the widget, mirrored by frontend/src/components/Widget/retroSkin.js customRetroSkin() for the settings preview; keep the ratios in sync. Admin UI: Settings → Widget → Colors → Retro IM → Retro IM Skin ("Colours the Retro IM window and its bubble launcher"), swatch per skin + Custom with Main Color / Title Text (moved here from the Widget tab in 5412d6ba). The retro bubble launcher uses the skin colours, not bubble_widget. Preview: components/Widget/RetroWidgetPreview.vue.

Welcome close button (2026-10-08, backend 91773940b, frontend b4aea0dd, widget 58f487a): welcome_widget_colors.close_btn_color / close_btn_icon — Settings → Widget → Colors → Welcome → Expanded Card Close Button / Close Icon. Empty = follow chat_btn_color (the pre-setting behaviour) and white icon, so old widgets look unchanged. Also accepted by the playground config (PlaygroundController).

Live tag — widget_design.live_tag.enabled is a toggle on Settings → Widget → Channels ("Show a "Live" indicator when an agent is online"); absent = shown, the widget hides it only on explicit false. Colour is editable only in the playground (Advanced → Appearance → Live Tag / Live Tag Color, 8afb26c2); the schema default background_color is the word 'red', so the playground editor substitutes #ef4444. live_tag must be sent with the whole widget_design object on save or it resets.

Readable button text (widget 8f58ac9, 2026-10-09): utils/color.ts readableTextOn(bg) → #1e293b or #ffffff by YIQ brightness (> 150 = dark text). It is the fallback when a button has a background but no text/icon colour (Bar, Bubble, Smart, Ultimate, Welcome) — playgrounds seeded from agency defaults had lost their stored text colours and a fixed white/dark fallback was unreadable. Explicit *_icon / text_color values still win.

Brand-colour match — Settings → Widget → Colors Match my website (showBrandMatch, company context only, not agency defaults/playground) calls POST /company/brand-colors { mode: 'preview' } and emits the returned dotted paths into the form; the owner saves. Auto-apply at onboarding/playground creation and the brand_colors field are documented in Onboarding.

Top-level color / layout fields​

FieldWhat
companies.primary_colorHighlights (links, ticks, accents)
companies.secondary_colorSecondary accent
companies.positionLauncher side: right (default) or left
companies.chat_widget_typeextend or small — chat window size

Visitor-facing copy​

FieldWhere it shows
launcher_textBubble launcher CTA label (default "Let's Talk"; empty → i18n launcher.letsTalk)
online_title_text / _sub_headingLauncher header/subheading during working hours
offline_title_text / _sub_headingLauncher outside working hours
communication_options.chat_labelChat button label
communication_options.video_call_labelVideo button label
communication_options.audio_call_labelAudio button label
agent_connection_request_textText shown while connecting to an agent
privacy_policy_text / privacy_policy_urlPrivacy link in the widget

Chatbot / pre-chat questions​

FieldWhat
chatbot_online_questions[]Questions asked before connecting to a live agent (online)
chatbot_online_messageGreeting when online
chatbot_online_after_questions_messageConfirmation after answers submitted
chatbot_offline_questions[]Equivalent set for offline (email-fallback flow)
chatbot_offline_message / _after_questions_messageEquivalent offline copy

Contact-information questions​

companies.contact_information_questions controls what's asked before chat or call. In the modern schema each is { enabled: boolean, question: string }:

name: { enabled, question }
email: { enabled, question }
phone: { enabled, question }

Plus take_phone_number_before_call — phone becomes mandatory before a call when true.

Call screen background​

Specific to the call interface:

  • widget_design.call_background.background_color / .background_image
  • For the call auto-trigger popup: call_auto_trigger.call_background.*, call_auto_trigger.text_color, and call_auto_trigger.auto_connect_video_file (FileModel id, uploaded via Default Videos).
  • Per AI call interface: ai_calling.call_interface (background_color, controller_bar_color, icon_color, hide_connecting_steps, hide_latest_message, avatar_image, agent_name).
widget_whitelabel.is_enable: boolean
widget_whitelabel.text: string // "Powered by ..."
widget_whitelabel.url: string // link target

When is_enable is false, the default "Powered by Knock Knock" appears. The nested widget_design.footer.hide_knock_logo / hide_powered_by flags can also suppress the default branding. Availability depends on plan/agency.

Mobile vs desktop​

  • mobile_disable: true — hide on mobile entirely.
  • mobile_launcher_style — a separate launcher style on mobile (falls back to desktop style).

Backend a7c180c01, frontend 14c7561f. video_gallery: [{ video_file (ObjectId → files), has_audio }] — the company's own uploads (max 10, MAX_VIDEO_GALLERY in CompanyController, mirrored in WidgetTab.vue). The widget still plays companies.video_file; the gallery is only the pick list. Upload posts gallery=true to POST /company/video so a new file is appended instead of replacing; has_audio is per item (an uploaded photo becomes a silent MP4). Delete = POST /company/video { remove_gallery_video: <file id> }; deleting the playing video also clears video_file server-side. A pre-gallery custom video_file (not a template, not in the gallery) is shown as a custom item and moved into the gallery on the next upload. Settings list = gallery first, then default templates. Tests: test/company-video-gallery.spec.js.

Video framing (widget_positions)​

The settings preview lets the admin drag the greeting video ("Drag video to reposition"); the pan is saved as widget_positions.<slot> = { x, y } (percent object-position). Since a02d6ba2 / 1086aaf3 (2026-09-28) the pointer handlers are delegated from the preview wrapper and resolve the <video> on every press (the preview swaps the element when a widget expands/collapses), and the slot comes from the widget actually on screen — positionKeyFor(): .bubble-main → bubble, .smart-widget-video-section → middle, .kk-widget-main-screen-wrapper-inner → expended, else previewType. A press that moves ≤3 px is a tap (form stays clean), and the click that ends a real drag is swallowed so a Bubble doesn't expand mid-gesture.

Configuration & options​

All settings above are edited in Settings → Widget, split across tabs:

TabCovers
WidgetLauncher style (desktop/mobile), online/offline titles
Colorswidget_design.*, per-style palettes, primary_color, theme presets
StyleLayout/position, chat window size, footer/whitelabel
ChannelsChannel toggles + labels, pre-chat/contact questions

The Colors tab ships theme presets (Default, Purple, Warm, Ocean, Dark, Green) as quick starting points.

Behaviors & edge cases​

  • Two schemas coexist (nested widget_design.* vs older flat fields). When debugging a color that "won't change," check which schema the serving codebase (modern vs legacy) reads.
  • Per-style palettes override core for that launcher — e.g. Welcome's button colors come from welcome_widget_colors, not widget_design.btn_*.
  • widget.css colour sanitising (7e4a68b90): company colour fields rendered into widget.css must be a CSS colour (hex, name, rgb()/hsl()); anything else falls back to the schema default.
  • Changes are session-fresh: config is fetched per visitor load, so a hard refresh of the customer's site shows new colors with no redeploy.
  • Contrast: receiver/sender bubble colors should meet WCAG-AA against the chat window background — there is no automatic contrast guard.
  • Position left is supported but unusual; useful when the site already has a right-side cart drawer.
  • Whitelabel/branding hide flags depend on plan and may be ignored on tiers that don't allow branding removal — verify.

Plan & limits​

  • Color and copy customization is available on all plans.
  • Whitelabel footer replacement and branding-hide flags depend on plan/agency tier — verify against the plan matrix.

Technical implementation​

  • Types: widget/src/types/company.ts — WidgetDesign, SmartWidgetColors, ExtendedWidgetColors, PillWidgetColors, WelcomeWidgetColors, BubbleWidgetColors, CallInterface, ContactInformationQuestions.
  • Store color mapping: widget/src/stores/widget.ts — WidgetColors / WidgetSettings and the mapping from company config to runtime colors.
  • Styles (SCSS): widget/src/assets/scss/ — per-component partials (_chat-widget.scss, _bubble-widget.scss, _smart-widget.scss, _ultimate-widget.scss, _ai-voice-widget.scss, _video-call-widget.scss).
  • Admin UI: frontend/src/views/settings/widget/tabs/ColorsTab.vue, StyleTab.vue, ChannelsTab.vue, ColorInput.vue.
  • Nox: can report "what colors are configured?", "what does the offline message say?", and "is whitelabel on?" by reading widget_design and friends. Changes go through settings-by-chat (on for every company since 2026-09-25) with a confirm card; uploads (logo, greeting media) stay human-only.
  • See the engineering service page: /services/widget.