Skip to navigation
Products & Surfaces

Widget theming and customization

Customize the chat widget’s colors, typography, layout, launcher, and content in Appearance in the workbench. The classic dashboard provides these controls in the Chat Style Editor on the Ship tab.

Before you begin

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

The steps on this page use the workbench. Differences in the classic dashboard lists what changes in the classic view. To change views, select Switch to the workbench in the account menu, or Switch to the classic dashboard in the Runtype menu in the workbench.

Open the theme editor

Open a chat Surface and select Appearance. The editor has these tabs:

  • Generate: Create a theme from a website URL or a description.
  • Style: Edit brand colors, chat colors, launcher appearance, typography, runtime theme, shape, shadows, and widget surface settings.
  • Design: Edit component shapes, component colors, suggestion styles, shadows, and header and welcome text.
  • Configure: Edit content, layout, launcher settings, and widget features.

Start from a preset

Select a preset from the Presets menu, then adjust its settings. The menu includes Clean, Midnight, Forest, Sunset, Ocean, Lavender, Noir, Rose, Cyberpunk, Vintage, Persona Default, Default Light, Default Dark, and High Contrast.

To create a theme from your website or a description instead, select Generate. For details, see AI-powered theme generation.

Customize colors

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

  • Primary: Set the main brand color for buttons, links, and accents.
  • Secondary: Set a supporting brand color.
  • Accent: Set a highlight or decorative color.
  • Chat colors: Set 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.

To add a separate dark theme, turn on Dark mode, select Dark, and set the dark colors. The widget does not invert colors automatically. It uses the dark colors that you set. When you first turn on Dark mode, Runtime theme in the Style tab is set to Follow System. With that setting, the widget shows the dark theme when the host page’s <html> element has the dark class. Otherwise, it follows the visitor’s system setting. To always show one theme, set Runtime theme to Light or Dark.

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, suggestion styles, and the typography for header and welcome text.

Use the Configure tab to change content, layout, and launcher settings:

  • 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, subtitle, and mobile behavior. To position the launcher, set Position to Bottom Right, Bottom Left, Top Right, or Top Left.

The workbench does not show the launcher title, the agent icon text and name, the icon image URL, the header icon name, or the avatar URLs. Unless a launcher title was saved in the classic dashboard, the copied snippet uses the Surface name as the launcher title.

When you click Save, the Surface keeps the theme, the dark theme, the runtime theme, content text, layout, message actions, launcher settings (including the close and clear chat buttons), and attachments. Other Configure sections change only the preview, and Save does not keep them. These include Suggestions, Send button, Status indicator, Features, Stream animation, Artifacts, and Tool calls and reasoning. To use these settings on your site, set them in the widget config object, for example suggestionChips, sendButton, or features.showToolCalls.

Preview and save changes

The preview updates as you edit.

  1. Select Desktop or Mobile in the preview toolbar.
  2. Choose a preview scene: Conversation, Home, Minimized, or Artifact.
  3. If Dark mode is on, select Light or Dark to review each theme.
  4. To check readability, click Check contrast. The editor shows the text-to-background ratio and whether it passes WCAG AA.
  5. Click Save to save the Surface.

Update an embedded widget

The embed snippet contains the theme values, so a site that runs an earlier snippet keeps its old style. After you save a new style, copy the snippet again and replace it on your site:

  1. Open Embed.
  2. In the Snippet card, select Script tag or React.
  3. Select a client token. If you select a live token, paste the token value that you saved when you created or regenerated it into Saved live token.
  4. Click Copy.

The snippet and the Integration prompt include the theme, the dark theme and color scheme, layout, message actions, welcome title and subtitle, and the launcher title, subtitle, and position. They do not include other saved settings, such as Input Placeholder, Send Button Label, launcher width, mobile behavior, icons, or attachments. Add these to the config object by hand, for example copy.inputPlaceholder, launcher.width, or attachments.

Edit the theme in code

Neither editor includes a custom CSS field. For token-level control, add the theme property to the widget config object.

The theme object uses three layers:

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

Set brand colors in palette.colors. Provide only the values that you want to change. The widget fills omitted values from its defaults. To set a dark theme, add darkTheme with the same structure as theme, and set colorScheme to auto, light, or dark. The following JSON shows a partial configuration:

Theme configuration
{
  "theme": {
    "palette": {
      "colors": {
        "primary": { "500": "#262626" },
        "accent": { "500": "#6366f1" }
      },
      "radius": { "sm": "6px" }
    }
  },
  "darkTheme": {
    "palette": {
      "colors": {
        "primary": { "500": "#e5e5e5" }
      }
    }
  },
  "colorScheme": "auto"
}

To theme the widget from an AI coding assistant, connect the Runtype MCP server. The get_persona_theme_reference tool returns the theme token reference, the default palette, and example themes. The generate_persona_embed_code tool accepts theme and color_scheme and returns a themed snippet.

Differences in the classic dashboard

To open the Chat Style Editor, open your Product, select the chat Surface, and select the Ship tab. In the It should use sentence, click the selected style, such as Clean style.

The classic editor differs from the workbench in these ways:

  • Save: Click Use Style instead of Save. The same Configure sections change only the preview.
  • Launcher and avatars: Configure also shows the launcher title, the agent icon text and name, the icon image URL, the header icon name, and the avatar URLs.
  • Generate: Select URL or Describe. You can attach reference images with Describe.
  • Custom presets: Select Save Current as Preset from the preset menu. Custom presets are saved in your browser only. Other team members, other browsers, and the workbench do not see them. To share a style, save it to the Surface.
  • Embed code: Select code it myself on the Ship tab, choose React or Script tag under Integration format, then click Copy code.
  • Mobile: The mobile editor also includes a Preview tab.

Next steps