Products & Surfaces

Widget theming and customization

Customize the chat widget’s colors, typography, layout, launcher, and content in the Chat Style Editor.

Before you begin

Create a Product with a chat Surface. For setup instructions, see Setting up a chat Surface.

Open the Chat Style Editor

To open the Chat Style Editor, follow these steps:

  1. Open your Product.
  2. Select the chat Surface.
  3. Select the Ship tab.
  4. In Widget Appearance, click Customize.

The Chat Style Editor includes these tabs:

  • Generate: create a theme from a website URL, a description, or reference images.
  • Style: edit brand colors, chat colors, typography, launcher appearance, theme mode, shape, shadows, and widget surface settings.
  • Design: edit component shapes, component colors, suggestions, shadows, and header and welcome text.
  • Configure: edit content, layout, launcher settings, and widget features.

The mobile editor also includes a Preview tab.

Customize colors

Use the following controls in the Style tab to customize the widget’s colors:

  • Primary: sets the main brand color for buttons, links, and accents.
  • Secondary: sets a supporting brand color.
  • Accent: sets a highlight or decorative color.
  • Chat Colors: sets colors for the header, user messages, and assistant messages.

Enter a hex value or choose a color in the color picker. The editor generates a shade scale from each brand color.

Set typography

Use the following controls in the Style tab to customize typography:

  • Font Family: Choose Sans Serif, Serif, or Monospace.
  • Base Font Size: Choose a size from Extra Small through Extra Large.
  • Font Weight: Choose Normal, Medium, Semibold, or Bold.
  • Line Height: Choose Tight, Normal, or Relaxed.

Change layout and content

Use the Style tab to set shape, shadow, launcher, panel, message, input, composer, and button styles.

Use the Design tab to set component shapes and colors. You can also edit suggestions and the typography for header and welcome text.

Use the Configure tab to change content, layout, launcher settings, and features. The following controls cover common widget changes:

  • Content: Set Welcome Title, Welcome Subtitle, Input Placeholder, and Send Button Label.
  • Layout: Show or hide the header, title, subtitle, close button, and clear chat control. Set the message style, avatars, and timestamps.
  • Widget > Launcher: Set the launcher position, width, title, subtitle, icon, and mobile behavior.

To position the launcher, set Position to Bottom Right, Bottom Left, Top Right, or Top Left.

Edit the theme in code

The Chat Style Editor does not include a custom CSS field. For token-level control, add the theme property to the widget config object.

The theme object uses three layers:

  • palette: stores primitive values for colors, spacing, typography, shadows, borders, and radius.
  • semantic: maps design intents to palette references, such as semantic.colors.primary mapping to palette.colors.primary.500.
  • components: stores per-component tokens for elements such as button, input, launcher, panel, header, and message.

Set brand colors in palette.colors. Provide only the values that you want to change. The widget fills omitted values from its defaults. The following JSON shows a partial theme configuration:

Theme configuration
1{
2  "theme": {
3    "palette": {
4      "colors": {
5        "primary": { "500": "#262626" },
6        "accent": { "500": "#6366f1" }
7      },
8      "radius": { "sm": "6px" }
9    }
10  }
11}

The generated embed code includes saved theme settings. To copy it, select With Code on the Ship tab.

Preview and save changes

The preview updates as you edit. To review and save a theme, follow these steps:

  1. Change a setting in the Style, Design, or Configure tab.
  2. Select Desktop or Mobile in the preview toolbar.
  3. If you turn on Dark mode support, select the light or dark shell background to review each theme.
  4. Click Use Style to save the widget configuration to the Surface.

Use a theme preset

The editor includes Clean, Midnight, Forest, Sunset, Ocean, Lavender, Noir, Rose, Cyberpunk, and Vintage. It also includes Persona Default, Default Light, Default Dark, and High Contrast.

Select a preset from the preset menu, then adjust its settings. To save your settings as a preset, open the preset menu and select Save Current as Preset.

Generate a theme with AI

On the Generate tab, choose URL or Describe. Enter a website URL or a description. When you choose Describe, you can attach reference images. Click Generate theme to apply the generated values to the preview.

Next steps

Continue with one of these guides: