Customize the v6 widget

This page documents the supported styling surface for the Chatlio v6 widget. The legacy v5 widget uses light-DOM selectors instead; see the v5-to-v6 migration guide.

Choose the v6 host selector

There are two supported embed paths. A direct-v6 embed loads w.chatlio-widget-v6.js itself and mounts <chatlio-widget>. The stable loader instead retains <chatlio-widget> as its loader owner and mounts the v6 root separately as <chatlio-widget-v6>. CSS custom properties only inherit to descendants, so a property placed only on the stable loader’s <chatlio-widget> does not reach the separate v6 root.

Always target both host tags. This covers direct-v6 and stable-loader embeds, and lets properties cross the v6 Shadow DOM without depending on implementation class names.

<script async src="https://w.chatlio.com/v6/w.chatlio-widget-v6.js"
  data-widget-id="YOUR-WIDGET-ID"></script>

chatlio-widget,
chatlio-widget-v6 {
  --chatlio-primary: #0057b8;
  --chatlio-on-primary: #fff;
  --chatlio-width: 400px;
  --chatlio-bottom-offset: 24px;
  --chatlio-right-offset: 24px;
}

CSS custom properties

Property	Default	Purpose
`--chatlio-primary`	`#4041f4`	Header, launcher, primary actions, and visitor bubble color.
`--chatlio-primary-dark`	`#3535d4`	Hover/active shade for primary controls. Set it with `--chatlio-primary` when supplying a brand color.
`--chatlio-on-primary`	`#ffffff`	Foreground used by primary controls.
`--chatlio-title-fg`	`var(--chatlio-on-primary)`	Launcher and open-header foreground. Dashboard title-font configuration overrides this value.
`--chatlio-text` / `--chatlio-subtext`	`#021930` / `#677583`	Main and secondary text.
`--chatlio-background` / `--chatlio-border`	`#ffffff` / `#e4eaf0`	Window surface and borders.
`--chatlio-online` / `--chatlio-error`	`#46c86d` / `#e84354`	Online indicator and error/badge color.
`--chatlio-msg-them-bg` / `--chatlio-msg-them-text`	`#f8fbfc` / `#021930`	Operator message bubble.
`--chatlio-msg-me-bg` / `--chatlio-msg-me-text`	`#4041f4` / `#ffffff`	Visitor message bubble.
`--chatlio-width` / `--chatlio-height`	`370px` / `550px`	Desktop standard-widget window dimensions.
`--chatlio-border-radius`	`20px`	Window and related rounded-corner geometry.
`--chatlio-font`	system UI stack	Widget typeface.
`--chatlio-bottom-offset`	`0px`	Standard/sidebar distance from the bottom edge.
`--chatlio-left-offset` / `--chatlio-right-offset`	`0px` / `0px`	Standard/sidebar horizontal distance; the active value follows dashboard alignment.
`--chatlio-z-index`	`9999999`	Stacking level of the widget container.

Offsets apply to standard and sidebar layouts. Inline widgets are in normal document flow, so their offsets do not apply. CSS offsets are the baseline; spacing supplied at runtime through _chatlio.setEdgeSpacing() is added to that baseline, and _chatlio.clearEdgeSpacing() clears only the runtime portion. At viewports of 480px or less, v6 intentionally fills the available viewport and ignores placement offsets to keep controls reachable; --chatlio-z-index still applies.

Dashboard Appearance settings remain supported. In particular, its title and title-font colors set the primary/header variables for that endpoint.

Stable parts

Use ::part() for targeted presentation that a variable cannot express. These names are the public contract; do not target .chatlio-* implementation classes. The current components render in the root widget shadow tree, so no exportparts attribute is needed. If a future component gains its own shadow root, its public parts will be explicitly re-exported before that change ships.

Part	Element / purpose
`container`	Fixed layout container.
`launcher`, `launcher-close`	Collapsed launcher and expanded close control.
`window`	Open chat surface.
`header`, `header-avatar`, `header-title`	Conversation header.
`messages`	Scrollable message transcript.
`message-me`, `message-them`	Visitor and operator message bubbles.
`composer`, `input-area`	Composer wrapper. `input-area` is the retained alias for existing customizations.
`input`	Composer textarea.
`attach-button`, `send-button`	Composer action controls.
`form`	A displayed pre-chat, offline, request-info, or conversation-end form.
`pre-chat-form`, `offline-form`, `request-info-form`, `conversation-end`	Specific form variants.
`footer`	Footer region containing branding when the account is not white-labelled.

For example, this makes only operator bubbles more compact:

chatlio-widget::part(message-them),
chatlio-widget-v6::part(message-them) {
  border-radius: 8px;
  font-size: 14px;
}

v5-to-v6 migration

V5 CSS selectors do not penetrate the v6 Shadow DOM. Translate common legacy overrides to this supported surface instead.

Legacy v5 intent	V6 replacement
`#chatlio-widget .chatlio-widget-body { width/height: ... }`	`--chatlio-width`, `--chatlio-height`
`#chatlio-widget-container { bottom/right/left: ... }`	`--chatlio-bottom-offset`, `--chatlio-right-offset`, `--chatlio-left-offset`
Raise/lower the widget above a site overlay	`--chatlio-z-index`
Title bar / launcher colors	Dashboard Appearance colors, or `--chatlio-primary`, `--chatlio-on-primary`, `--chatlio-title-fg`
Visitor/operator bubble colors	`--chatlio-msg-me-` and `--chatlio-msg-them-`
Target title, transcript, or composer markup	`::part(header-title)`, `::part(messages)`, `::part(composer)`
Target an individual message direction	`::part(message-me)` or `::part(message-them)`

Do not try to mechanically translate arbitrary v5 selectors, pseudo-elements, or animation overrides. Test v6 beside v5 first, especially for customized launchers, mobile layouts, and host-page overlays.