> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyreach.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Appearance and branding

> Theme the launcher and chat window, and auto-brand from a domain.

The **Theming** tab of the Widget Builder controls how the widget looks: the launcher button, the chat window, per-mode colors, and where the widget sits on the page. Everything you set here is stored under `config.v1` on the widget. You can also auto-brand from a domain, which pulls colors and logos from your website and writes them into the same fields.

This page is a reference for the appearance fields. For the message text, default mode, and quick actions, see [Text, voice, and quick actions](/web-widgets/text-voice-and-quick-actions). To create the widget in the first place, see [Creating a widget](/web-widgets/creating-a-widget).

<Note>
  Editing appearance requires the `web_widgets:manage` scope. `web_widgets:read` is view-only.
</Note>

## Theme

The **Theme** select decides which color scheme the widget renders in.

| Value    | Behavior                                                            |
| -------- | ------------------------------------------------------------------- |
| `system` | Follow the visitor's OS or browser preference. This is the default. |
| `light`  | Always render in light mode.                                        |
| `dark`   | Always render in dark mode.                                         |

The value is stored at `config.v1.theme`.

## Colours

Colors are defined separately for **Light Mode** and **Dark Mode** so the widget looks right in either theme. Each mode exposes the same four tokens.

| UI label                 | Used for                     | `config.v1.chat` path                     |
| ------------------------ | ---------------------------- | ----------------------------------------- |
| **Primary Background**   | User messages, active states | `<mode>.background_color.user_message`    |
| **Primary Text**         | User message text            | `<mode>.text_color.user_message`          |
| **Secondary Background** | Send button, controls        | `<mode>.background_color.controls_button` |
| **Secondary Text**       | Input text, icons            | `<mode>.text_color.controls_button`       |

`<mode>` is `light_mode` or `dark_mode`. Each is a theme object with `background_color` and `text_color` maps. Leave a token empty to fall back to the built-in default for that mode.

<Note>
  Surfaces like the message background, header, input, and agent response text are fixed neutral colors and are not themed by these four tokens.
</Note>

## Launcher button

The launcher is the floating button visitors click to open the widget. Its fields live under `config.v1.trigger`.

| UI label              | Field             | Type                 | Default        | Description                                                                                    |
| --------------------- | ----------------- | -------------------- | -------------- | ---------------------------------------------------------------------------------------------- |
| **Shape**             | `shape`           | `circle` \| `square` | `circle`       | Setting the shape also sets `chat.avatar_shape` to match.                                      |
| **Size**              | `size`            | number (px)          | `56`           | Presets: XS `40`, S `48`, M `56`, L `64`, XL `72`. Each preset also sets a matching `padding`. |
| **Button Background** | `backgroundColor` | string               | —              | Hex color for the launcher background.                                                         |
| **Padding**           | `padding`         | number (px)          | `~20%` of size | Space between the button edge and the avatar. Slider range `0`–`50`.                           |
| **Use Avatar**        | `avatarUrl`       | string               | —              | Toggle on to upload a launcher image. When off, a default icon is shown.                       |

### Per-mode launcher overrides

By default the launcher uses the single `backgroundColor` and `avatarUrl`. Toggle **Override dark mode** or **Override light mode** to set mode-specific values under `trigger.dark` and `trigger.light`. Each override block accepts:

| Field             | Description                             |
| ----------------- | --------------------------------------- |
| `backgroundColor` | Launcher background for that mode.      |
| `textColor`       | Launcher text/icon color for that mode. |
| `avatarUrl`       | Launcher avatar for that mode.          |

When a mode override is set, it takes precedence over the top-level `backgroundColor` and `avatarUrl` for that mode.

## Chat window

Turn on **Use Avatar** under **Chat window** to give the agent a custom avatar inside the open chat. You upload a **Light Avatar** (`chat.avatar_url`) and an optional **Dark Avatar** (`chat.dark_avatar_url`).

When the chat avatar is disabled, the chat window falls back to the launcher avatar, or to the default Orb.

## Position

The launcher is anchored to the bottom-right corner. Set its offsets in pixels under `config.v1.position`.

| UI label   | Field             | Default | Description                                            |
| ---------- | ----------------- | ------- | ------------------------------------------------------ |
| **Right**  | `position.right`  | `24`    | Distance from the right edge, in pixels. Minimum `0`.  |
| **Bottom** | `position.bottom` | `24`    | Distance from the bottom edge, in pixels. Minimum `0`. |

## config.v1 structure

All appearance and content settings live under `config.v1`. The relevant shape:

```json theme={null}
{
  "v1": {
    "theme": "system",
    "position": { "right": 24, "bottom": 24 },
    "trigger": {
      "shape": "circle",
      "size": 56,
      "padding": 12,
      "backgroundColor": "#18181B",
      "avatarUrl": "https://.../launcher.png",
      "dark":  { "backgroundColor": "...", "textColor": "...", "avatarUrl": "..." },
      "light": { "backgroundColor": "...", "textColor": "...", "avatarUrl": "..." }
    },
    "chat": {
      "name": "Support",
      "avatar_url": "https://.../avatar-light.png",
      "dark_avatar_url": "https://.../avatar-dark.png",
      "avatar_shape": "circle",
      "welcome_title": "Hi there",
      "welcome_description": "How can we help?",
      "start_button_text": "Start chat",
      "privacy_policy_url": "https://example.com/privacy-policy",
      "disable_powered_by_anyreach": false,
      "light_mode": {
        "background_color": { "user_message": "#...", "controls_button": "#..." },
        "text_color":       { "user_message": "#...", "controls_button": "#..." }
      },
      "dark_mode": {
        "background_color": { "user_message": "#...", "controls_button": "#..." },
        "text_color":       { "user_message": "#...", "controls_button": "#..." }
      }
    }
  }
}
```

The `chat` object also holds content fields that are not part of the Theming tab:

| Field                         | Type    | Description                                            |
| ----------------------------- | ------- | ------------------------------------------------------ |
| `name`                        | string  | Agent name shown in the chat header.                   |
| `welcome_title`               | string  | Heading on the pre-chat screen.                        |
| `welcome_description`         | string  | Subheading on the pre-chat screen.                     |
| `start_button_text`           | string  | Label on the button that opens the chat.               |
| `privacy_policy_url`          | string  | Link shown at the bottom of the chat.                  |
| `disable_powered_by_anyreach` | boolean | When `true`, removes the "Powered by Anyreach" footer. |

See [Text, voice, and quick actions](/web-widgets/text-voice-and-quick-actions) for the content and mode fields.

## Auto-Brand

Auto-Brand fills in colors and logos from a domain so you do not have to set them by hand. Enter a domain in the **Auto-Brand** box at the top of the Theming tab and fetch it. Anyreach looks up the domain through [brand.dev](https://brand.dev) and applies the result to `config.v1`.

<Steps>
  <Step title="Enter a domain">
    Type your website domain (for example `example.com`) and run the fetch. The protocol, `www.`, and a trailing slash are stripped automatically.
  </Step>

  <Step title="Anyreach retrieves the brand">
    The platform calls brand.dev for that domain and returns the brand's logos, colors, company info, and social links.
  </Step>

  <Step title="Values are applied to config.v1">
    The fetched data is merged into the current config. Review the result and click **Save changes** to keep it.
  </Step>
</Steps>

### What Auto-Brand sets

| Source from brand.dev          | Applied to                                                                                                         |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| First brand color              | `trigger.backgroundColor`, and `user_message` / `controls_button` backgrounds in both `light_mode` and `dark_mode` |
| Contrast of the first color    | `user_message` / `controls_button` text colors in both modes (black or white, whichever is readable)               |
| `icon` logo, else `light` logo | `chat.avatar_url`                                                                                                  |
| `dark` logo                    | `chat.dark_avatar_url`                                                                                             |
| —                              | `theme` is set to `light` and `trigger.padding` is set to `14`                                                     |

<Note>
  Auto-Brand overwrites the color and avatar fields above. Other fields, such as `name`, `welcome_title`, and your launcher size and position, are preserved.
</Note>

### Endpoint

The Theming tab calls this endpoint behind the scenes. You can call it directly to fetch brand data for a domain.

```bash theme={null}
curl -X POST https://api.anyreach.ai/core/web-widgets/{id}/auto-brand \
  -H "Authorization: Bearer <token>" \
  -H "X-Anyreach-Org: <organization_id>" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com" }'
```

The body takes a single `domain` field. The response is the brand object (logos, colors, company, socials) from brand.dev. The endpoint requires the `web_widgets:manage` scope. Applying that response to `config.v1` happens client-side; the endpoint itself only fetches the brand data.

<Warning>
  Replace `{id}` with the widget ID. User personal access tokens (`pat_`) must also send `X-Anyreach-Org`; organization API keys (`ak_`) carry their org implicitly and omit it.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Text, voice, and quick actions" icon="message-dots" href="/web-widgets/text-voice-and-quick-actions">
    Configure welcome copy, default mode, and quick-action buttons.
  </Card>

  <Card title="Creating a widget" icon="plus" href="/web-widgets/creating-a-widget">
    Create a widget and walk through the Widget Builder tabs.
  </Card>
</CardGroup>