Customize the Agentforce Commerce Client
There are different ways to customize the Agentforce Commerce Client. These customization methods apply to SFRA, PWA Kit, and Storefront Next storefronts.
- Configuration: Use the configuration object for your storefront type to change supported text, colors, branding, layout, and behavior. Use configuration and theme properties to cover most brand and behavior needs with no code.
- CSS: Use custom CSS to style and theme the
cim-widget-*classes, withglobalClassNameas a specificity hook. This restyles what the widget already renders without changing its structure.
To replace the client components with your own, use the Component Override SDK. The SDK enables you to restructure product detail cards or carousels, cart management, product comparisons, and render a custom agent-action block. See Override Commerce Client UI Components.
This table lists the different kinds of customizations and which method you can use.
| Customization | Configuration | Custom CSS |
|---|---|---|
| Brand colors, fonts, borders | Yes | Yes |
| Header logo and title | Yes | Yes |
| Presentation mode (chat, dialog, modal) | Yes | Partial |
| Restyle an existing element | No | Yes |
Configuration properties and CSS controls are separate interfaces. Use configuration for supported widget options. Use CSS custom properties and cim-widget selectors to refine rendered styles. The corresponding names and syntax differ.
The Agentforce Commerce Client is flexible and customizable. It doesn’t ship with a CSS framework and has no global resets. Every element carries a cim-widget- class prefix, so styles won’t interfere with your page layout. Conversely, your storefront styles never affect the widget’s appearance. You style the widget using three distinct layers: theme properties, header configuration, and custom CSS.
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.
| 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.
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. |
You can also modify the following properties to adjust how the client looks to the shopper.
Opt-in Icon
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.
Search Bar Customization
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.
Prompt Extensions
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).
The widget sets theme and header values as CSS custom properties, so you can also modify them in your own stylesheet.
Header properties follow the same convention with a --cim-widget-header- prefix (for example, --cim-widget-header-background-color).
When theme properties aren’t enough, target the widget’s classes directly. Every cim-widget-* class is a stable selector, for example:
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.