> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UI configuration

Customize the user interface (UI) of the chat to better fit your website's design and enhance the user experience. You can modify various aspects of the chat UI, including layout, styles, header options, and language settings.

Before customizing, review the [customization guidelines](customization_guidelines) to ensure your changes remain stable and supported across product updates.

This page covers the following configuration options:

* [**Header**](#header)
  * [`header.showResetButton`](#param-header-show-reset-button): Display the Reset Chat button.
  * [`header.showAiDisclaimer`](#param-header-show-ai-disclaimer): Display the AI disclaimer icon.
  * [`header.showMaximize`](#param-header-show-maximize): Display the Maximize chat button.
  * [`header.showAgentAvatar`](#param-header-show-agent-avatar): Display the agent avatar.
  * [`header.showAgentName`](#param-header-show-agent-name): Display the agent name.
* [**Features**](#features)
  * [`features.showThreadList`](#param-features-show-thread-list): Display chat history in the side panel.
  * [`features.showAgentMemory`](#param-features-show-agent-memory): Display the agent memory button.
* [**Language**](#language)
  * [`defaultLocale`](#param-default-locale): Set the default language.
* [**Styles**](#styles)
  * [`style.theme`](#param-theme): Set the chat color theme.
  * [`style.headerColor`](#param-header-color): Customize the header color.
  * [`style.userMessageBackgroundColor`](#param-user-message-background-color): Customize user message bubble color.
  * [`style.primaryColor`](#param-primary-color): Customize interactive elements color.
  * [`style.fontFamily`](#param-font-family): Set the font style.

## Header

Controls the visibility of chat header actions. To apply header configuration, add a `header` component inside the `window.wxOConfiguration` object in your web chat script. In this component, you can configure the following parameters:

<ParamField path="header.showResetButton" type="boolean" default="true">
  Displays the Reset Chat button in the header when set to true.

  ```javascript highlight={9} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    header: {
      showResetButton: true
    }
  };
  ```
</ParamField>

<ParamField path="header.showAiDisclaimer" type="boolean" default="true">
  Displays the AI disclaimer icon/button in the header when set to true.

  ```javascript highlight={9} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    header: {
      showAiDisclaimer: true
    }
  };
  ```
</ParamField>

<ParamField path="header.showMaximize" type="boolean" default="false">
  Controls the visibility of the 'Maximize chat' button in the chat header.

  You can combine this parameter with additional layout modifiers, such as:

  * **Custom elements:** Explicitly set height to the custom element (`layout.customElement`) to render the chat window within it.
  * **Layout and spacing:** Configure `layout.showMaxWidth` to switch between a constrained and full-width layout. A constrained layout adds visual breathing room around the content, while a full-width layout uses the entire chat area with minimal horizontal padding.

  ```javascript highlight={9,12} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    header: {
      showMaximize: true
    },
    layout: {
      showMaxWidth: true
    }
  };
  ```
</ParamField>

<ParamField path="header.showAgentAvatar" type="boolean" default="true">
  Hides the agent avatar in the header when set to `false`.

  ```javascript highlight={9} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    header: {
      showAgentAvatar: false
    }
  };
  ```
</ParamField>

<ParamField path="header.showAgentName" type="boolean" default="true">
  Hides the agent name in the header when set to `false`.

  ```javascript highlight={9} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    header: {
      showAgentName: false
    }
  };
  ```
</ParamField>

## Features

Control the visibility and behavior of chat features. To apply feature configuration, add a `features` component inside the `window.wxOConfiguration` object in your chat script. In this component, you can configure the following parameters:

<ParamField path="features.showThreadList" type="boolean">
  Controls the visibility of the chat history (thread list) in the side panel.

  **Default behavior varies by layout:**

  * **`fullscreen-overlay`**: defaults to `true`
  * **`float` and `custom`**: defaults to `false`

  When enabled, users can view and navigate their conversation history through the side panel.

  When disabled, the side panel displays only custom header items (if configured).

  You can explicitly set this to `true` or `false` to override the default behavior for any layout.

  <Note>
    In the Float and Custom form factors, the thread list can be hidden either by omitting the property (as `false` is the default) or by explicitly setting `showThreadList: false`. In the Full-screen form factor, however, you must explicitly set `showThreadList: false` to hide the thread list, as the default value is `true`.
  </Note>

  ```javascript highlight={9} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    features: {
      showThreadList: true
    }
  };
  ```
</ParamField>

<ParamField path="features.showAgentMemory" type="boolean" default="false">
  Controls the visibility of the agent memory button in the side panel.

  When enabled, users can access the agent memory button to view and delete their memories, or turn the feature off. When disabled, the agent memory button is not displayed.

  To configure memory for an agent, see the feature implementation in the [Understanding agent memory](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=chat-understanding-agent-memory) documentation.

  ```javascript highlight={9} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    features: {
      showAgentMemory: true
    }
  };
  ```
</ParamField>

## Language

Define the default language of the chat interface. To apply language configuration, add the following parameters inside the `window.wxOConfiguration` object in your web chat script:

<ParamField path="defaultLocale" type="string" default="en">
  Defines the default language supported by the chat.

  **Supported locale strings:**

  | Language              | Language code |
  | --------------------- | ------------- |
  | Chinese - Traditional | `zh-TW`       |
  | Chinese - Simplified  | `zh-CN`       |
  | Dutch                 | `nl`          |
  | English               | `en`          |
  | French                | `fr`          |
  | German                | `de`          |
  | Italian               | `it`          |
  | Japanese              | `ja`          |
  | Korean                | `ko`          |
  | Portuguese - Brazil   | `pt-BR`       |
  | Spanish               | `es`          |

  ```javascript highlight={8} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    defaultLocale: 'ja'
  };
  ```
</ParamField>

## Styles

You can customize embedded web chats to create a unique chat interface that better fits your webpage. To apply custom styles, add a `style` component inside the `window.wxOConfiguration` object in your web chat script. In this component, you can configure the following parameters:

<ParamField path="theme" type="string" default="light">
  Set the color theme for the embedded web chat. Supported values are `'light'` and `'dark'`. The light theme uses the [IBM Carbon `g10` theme](https://carbondesignsystem.com/elements/color/overview/#themes), and the dark theme uses the [IBM Carbon `g100` theme](https://carbondesignsystem.com/elements/color/overview/#themes).

  ```javascript highlight={9} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    style: {
      theme: 'dark'
    }
  };
  ```
</ParamField>

<ParamField path="headerColor" type="string">
  Set a six-digit hex code that defines the chat header color.

  ```javascript highlight={9} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    style: {
      headerColor: '#0f62fe'
    }
  };
  ```
</ParamField>

<ParamField path="userMessageBackgroundColor" type="string">
  Set a six-digit hex code that defines the user message bubble color.

  ```javascript highlight={9} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    style: {
      userMessageBackgroundColor: '#0f62fe'
    }
  };
  ```
</ParamField>

<ParamField path="primaryColor" type="string">
  Set a six-digit hex code that defines the interactive elements color.

  ```javascript highlight={9} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    style: {
      primaryColor: '#0f62fe'
    }
  };
  ```
</ParamField>

<ParamField path="fontFamily" type="string">
  Set a font style that needs to be applied.

  ```javascript highlight={9} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    style: {
      fontFamily: 'Arial, sans-serif'
    }
  };
  ```
</ParamField>

<ParamField path="showBackgroundGradient" type="boolean" default="true">
  Displays the background gradient when set to true.

  ```javascript highlight={9} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    style: {
      showBackgroundGradient: false
    }
  };
  ```
</ParamField>

## Layout

Control how and where the chat UI appears. To apply layout configuration, add a `layout` component inside the `window.wxOConfiguration` object in your web chat script. In this component, you can configure the following parameters:

<ParamField path="rootElementID" type="string">
  **Scope:** `fullscreen-overlay` only

  The ID of the container node to mount chat into.

  ```javascript highlight={4} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    rootElementID: "root",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    }
  };
  ```
</ParamField>

<ParamField path="showLauncher" type="boolean" default="true">
  **Scope:** `fullscreen-overlay` only

  Sets the initial launcher visibility: show the bubble launcher (true) or render chat immediately (false). To control launcher visibility at runtime for any layout mode, use the [`changeView()`](instance_methods#changeview) instance method.

  ```javascript highlight={5} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    rootElementID: "root",
    showLauncher: false,
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    }
  };
  ```
</ParamField>

<ParamField path="layout.form" type="string" default="float">
  Defines the layout form of your web chat.

  Use `fullscreen-overlay` to display the web chat in fullscreen mode. No additional parameters are required.

  Use `float` to display the web chat as a floating window. Also configure:

  * `width`: Width of the web chat
  * `height`: Height of the web chat

  Use `custom` to define a custom layout. Also configure the `customElement` parameter with your custom element.

  ```javascript highlight={9} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    layout: {
      form: 'float'
    }
  };
  ```
</ParamField>

<ParamField path="layout.width" type="string">
  **Scope:** `float` only

  Popup width (e.g. '350px', '30rem').

  ```javascript highlight={10} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    layout: {
      form: 'float',
      width: '600px'
    }
  };
  ```
</ParamField>

<ParamField path="layout.height" type="string">
  **Scope:** `float` only

  Popup height (e.g. '500px', '40rem').

  ```javascript highlight={10} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    layout: {
      form: 'float',
      height: '600px'
    }
  };
  ```
</ParamField>

<ParamField path="layout.showOrchestrateHeader" type="boolean" default="true">
  Render the standard header bar (true) or hide it (false).

  ```javascript highlight={9} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    layout: {
      showOrchestrateHeader: false
    }
  };
  ```
</ParamField>

<ParamField path="layout.showMaxWidth" type="boolean" default="false">
  Switch between a constrained and full-width layout. A constrained layout adds visual breathing room around the content, while a full-width layout uses the entire chat area with minimal horizontal padding.

  ```javascript highlight={9} theme={null}
  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    layout: {
      showMaxWidth: true
    }
  };
  ```
</ParamField>

<ParamField path="layout.customElement" type="HTMLElement">
  Element reference to render into.

  ```javascript highlight={1,11-12} wrap theme={null}
  const hostElement = document.getElementById('custom-chat-container');

  window.wxOConfiguration = {
    orchestrationID: "my-tenant-id",
    hostURL: "my-host-url",
    chatOptions: {
      agentId: "12345_test_agent1",
      agentEnvironmentId: "my-agent-env-id"
    },
    layout: {
      form: 'custom',
      customElement: hostElement
    }
  };
  ```
</ParamField>