> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# 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](/user-guide/products-surfaces/setting-up-a-chat-surface).

The steps on this page use the workbench. [Differences in the classic dashboard](#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](/user-guide/products-surfaces/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`**

```json title="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](/developer-guides/integrations/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

* [AI-powered theme generation](/user-guide/products-surfaces/ai-powered-theme-generation): generate a theme from a website URL, a description, or reference images
* [Embedding the chat widget (script tag)](/user-guide/products-surfaces/embedding-the-chat-widget-script-tag): add the configured widget to an HTML page
* [Embedding the chat widget (React)](/user-guide/products-surfaces/embedding-the-chat-widget-react): add the configured widget to a React app
* [Client tokens and domain restrictions](/user-guide/products-surfaces/client-tokens-and-domain-restrictions): restrict the browser origins that can use the widget