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):
| Group | Fields |
|---|---|
message.receiver | background_color, text_color (visitor's bubble) |
message.sender | background_color, text_color (agent / AI bubble) |
header | background_color, text_color |
footer | background_color, text_color, hide_knock_logo, hide_powered_by |
btn_video_call / btn_audio_call / btn_chat | background_color, text_color |
btn_down_arrow | background_color, text_color, arrow_position |
btn_submit_phone | background_color, text_color |
sticky_widget | background_color, icon_and_text_color |
call_background | background_color, background_image |
live_tag | background_color, text_color, enabled |
bubble_widget | background_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:
| Style | Object | Notable fields |
|---|---|---|
| Smart | smart_widget_colors | background_color, text_color |
| Ultimate (extended) | extended_widget_colors | video_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 Pill | pill_widget_colors | gradient_start, gradient_end, text_color |
| Welcome | welcome_widget_colors | pill_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 |
| Bubble | bubble_widget | background_color, text_color |
| Retro IM | retro_skin, retro_custom_colors | Preset 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
| Field | What |
|---|---|
companies.primary_color | Highlights (links, ticks, accents) |
companies.secondary_color | Secondary accent |
companies.position | Launcher side: right (default) or left |
companies.chat_widget_type | extend or small — chat window size |
Visitor-facing copy
| Field | Where it shows |
|---|---|
launcher_text | Bubble launcher CTA label (default "Let's Talk"; empty → i18n launcher.letsTalk) |
online_title_text / _sub_heading | Launcher header/subheading during working hours |
offline_title_text / _sub_heading | Launcher outside working hours |
communication_options.chat_label | Chat button label |
communication_options.video_call_label | Video button label |
communication_options.audio_call_label | Audio button label |
agent_connection_request_text | Text shown while connecting to an agent |
privacy_policy_text / privacy_policy_url | Privacy link in the widget |
Chatbot / pre-chat questions
| Field | What |
|---|---|
chatbot_online_questions[] | Questions asked before connecting to a live agent (online) |
chatbot_online_message | Greeting when online |
chatbot_online_after_questions_message | Confirmation after answers submitted |
chatbot_offline_questions[] | Equivalent set for offline (email-fallback flow) |
chatbot_offline_message / _after_questions_message | Equivalent 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, andcall_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).
Whitelabel footer
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).
Video gallery (companies.video_gallery, 2026-10-08)
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:
| Tab | Covers |
|---|---|
| Widget | Launcher style (desktop/mobile), online/offline titles |
| Colors | widget_design.*, per-style palettes, primary_color, theme presets |
| Style | Layout/position, chat window size, footer/whitelabel |
| Channels | Channel 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, notwidget_design.btn_*. widget.csscolour sanitising (7e4a68b90): company colour fields rendered intowidget.cssmust 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
leftis 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/WidgetSettingsand 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_designand 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.