---
schema_version: "1"
id: b5fbdb2ae12f301f7bce281f6bd0e99fc94505b6c50e561f31cdaaabbe38a21a
title: Style and Theme the Widget
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/b2c-commerce/guides/agentforce-commerce-client/style-and-theme-the-widget.md
canonical_url: https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/style-and-theme-the-widget.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 077c0cf53b9ee61a7e32c90b7de60668a56007e34f21b5585f49bd5f9291a15e
products:
  - Composable Storefront
  - Salesforce APIs
---
# Style and Theme the Widget

The Agentforce Commerce Client is non-opinionated: it ships with no CSS framework and applies no global resets. Every element carries a `cim-widget-` class prefix, so widget styles never leak into your page and your storefront styles never affect the widget. You style the widget in three escalating layers: theme properties, header configuration, and custom CSS.

## Theme properties

The `theme` object is the primary way to make the widget feel brand-native. A handful of properties cascade across every surface (buttons, messages, typography, borders, and corners), so a few lines of configuration reshape the widget's look with no custom CSS.

```ts
theme: {
  primaryColor: "#3182ce",
  secondaryColor: "#2c5282",
  fontColor: "#1a202c",
  fontFamily: "inherit",
  backgroundColor: "#ffffff",
  borderColor: "#dddddd",
  borderRadius: "0.25rem",
}
```

| Property | Applies to | Default |
| --- | --- | --- |
| `primaryColor` | Buttons, icons, and user message backgrounds | `#3182ce` |
| `secondaryColor` | AI response message backgrounds | `#2c5282` |
| `fontColor` | All text | `#1a202c` |
| `fontFamily` | Typography | `inherit` |
| `backgroundColor` | Widget canvas and container | `#ffffff` |
| `borderColor` | Outer borders (dialog and embedded modes) | `#dddddd` |
| `borderRadius` | Corner rounding | `0.25rem` |

A partial `theme` overrides only the values you set; every unset property falls back to its default.

Because `fontFamily` defaults to `inherit`, the widget automatically adopts whatever typeface your storefront uses. If your site rebrands to a new font, the widget follows with no configuration change. Stick to universally supported font values so the widget renders consistently even when a custom font hasn't loaded.

## Header configuration

The `headerConfig` object independently styles the widget header (logo, title text, and header chrome).

| Field | Type | Notes |
| --- | --- | --- |
| `logoUrl` | `string` | Logo image in the header. |
| `headerText` | `string` | Header title text. |
| `headerBackgroundColor` | `string` | Header bar background. Defaults to `transparent`. |
| `headerTextColor` | `string` | Header title color. Defaults to `inherit`. |
| `headerTextFontSize` | `string` | Header title size. Defaults to `1.25rem`. |
| `headerTextFontWeight` | `number` | Header title weight. Defaults to `bold`. |
| `headerTextFontFamily` | `string` | Header title typeface. Defaults to `inherit`. |
| `headerTextTextAlign` | `"left" \| "center" \| "right"` | Header title alignment. Defaults to `left`. |

## Other presentation options

A few more properties adjust presentation.

- **`suggestionButtonConfig`** adds an opt-in icon to the prompt and in-conversation suggestion buttons. Set `icon` to `"sparkle"`, `"plus"`, or `"paper-plane"`, and `iconPosition` to `"left"` (default) or `"right"`. No icon shows unless you set one.
- **`searchConfig`** customizes the search bar: `placeholder`, `buttonLabel`, `buttonAriaLabel`, `buttonIconUrl`, `buttonType` (`"icon"`, `"text"`, or `"icon-text"`), and `enableCancelSearch`. Set the search bar's placeholder and button label here through `placeholder` and `buttonLabel`.
- **`promptsConfig`** controls the prompts extension: `promptsDisplay` (`"input"`, `"buttons"`, or `"both"`, default `"both"`), `staticQuestions` (fixed questions rendered as buttons; trimmed and deduplicated, empties dropped), and `disableAskElseButton` (default `false`).

## CSS custom properties

The widget emits theme and header values as CSS custom properties, so you can also read or override them in your own stylesheet:

```css
--cim-widget-primary-color
--cim-widget-secondary-color
--cim-widget-font-color
--cim-widget-font-family
--cim-widget-background-color
--cim-widget-border-color
--cim-widget-border-radius
```

Header properties follow the same convention with a `--cim-widget-header-` prefix (for example, `--cim-widget-header-background-color`).

## Custom CSS for pixel-perfect control

When theme properties aren't enough, target the widget's classes directly. Every `cim-widget-*` class is a stable selector, for example:

```css
.cim-widget-container {
}
.cim-widget-message-container {
}
.cim-widget-suggestion-button {
}
.cim-widget-modal-title {
}
```

For an extra specificity hook, set the `globalClassName` property. The widget adds that class to all of its elements, giving you a scoped selector to raise specificity without editing the widget's source.

**Per-platform notes.** The `cim-widget-` classes are the same regardless of storefront framework, so custom CSS targets them the same way everywhere. Deliver that CSS through your storefront's normal styling pipeline:

- **SFRA:** add the rules to a cartridge stylesheet.
- **Composable Storefront (PWA Kit):** add the rules alongside your Chakra styles, scoped to the `cim-widget-` classes.
- **Storefront Next:** add the rules to your app's stylesheet; the `cim-widget-` prefix keeps them isolated from your utility classes.

Because the widget attaches no shadow root, your storefront CSS reaches these elements normally.

## Related resources

- [Configure the Agentforce Commerce Client](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/configure-the-commerce-client.md)
- [Choose a Customization Approach](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/customization-decision-guide.md)
- [Component Override SDK](https://developer.salesforce.com/docs/commerce/pwa-kit-managed-runtime/guide/component-override-sdk.md)