Custom Theming
Customize the appearance of the Kindly chat interface by setting your own color theme. The SDK provides two methods for theme customization:
- Using a complete Theme object
- Specifying individual colors
Setting a Complete Theme
Create and configure a custom theme by implementing the Theme protocol or using the provided CustomTheme struct:
// Create a custom theme
let darkTheme = CustomTheme(
background: UIColor.black,
botMessageBackground: UIColor.darkGray,
botMessageText: UIColor.white,
buttonBackground: UIColor.blue,
buttonText: UIColor.white,
userMessageBackground: UIColor.systemBlue,
userMessageText: UIColor.white,
chatLogElements: UIColor.lightGray
// Add other color properties as needed
)
// Apply the custom theme
KindlySDK.setCustomTheme(darkTheme)Setting Individual Colors
For convenience, you can also specify just the colors you want to customize without creating a complete theme:
KindlySDK.setCustomTheme(
background: UIColor.white,
botMessageBackground: UIColor.lightGray,
botMessageText: UIColor.black,
buttonBackground: UIColor.blue,
buttonText: UIColor.white,
userMessageBackground: UIColor.blue,
userMessageText: UIColor.white,
chatLogElements: UIColor.gray
// Only specify the colors you want to customize
)Available Theme Properties
The theme properties are divided into two categories:
API-defined Colors (from Kindly settings)
These colors are defined in the Kindly settings (app.kindly.ai) and are fetched with your bot configuration:
Property | Description |
|---|---|
background | Main background color of the chat interface |
botMessageBackground | Background color for bot message bubbles |
botMessageText | Text color for bot messages |
buttonBackground | Background color for buttons |
buttonOutline | Outline color for buttons |
buttonText | Text color for buttons |
chatLogElements | Color for chat log elements like timestamps |
navBarBackground | Background color for the navigation bar (maps to header_background in API) |
navBarText | Text color for the navigation bar (maps to header_text in API) |
inputBackground | Background color for the input field |
inputText | Text color for the input field |
userMessageBackground | Background color for user message bubbles |
userMessageText | Text color for user messages |
Manually Added Colors
These colors are not defined in the Kindly settings but are used by the SDK for additional UI elements:
Property | Description |
|---|---|
buttonSelectedBackground | Background color for selected buttons |
defaultShadow | Default shadow color |
inputCursor | Color for the input cursor |
maintenanceHeaderBackground | Background color for maintenance alerts |
Clearing Custom Theme
To clear a custom theme and revert to the default or API-provided theme:
KindlySDK.clearCustomTheme()This will:
- ✅ Remove any user-defined custom theme
- ✅ Revert to the theme from Kindly settings (if available)
- ✅ Fall back to the default SDK theme if no API theme exists
- ✅ Apply changes immediately to any displayed chat interface
Theme Priority
When setting a custom theme:
- User-defined theme (set via setCustomTheme) takes precedence over any other theme
- API theme (from Kindly settings configured in app.kindly.ai) is used if no user theme is set
- Default SDK theme is applied if neither user nor API themes are available
Theme Priority Examples
// Set a custom theme (highest priority)
KindlySDK.setCustomTheme(
background: UIColor.black,
botMessageBackground: UIColor.gray
)
// Later, clear custom theme to use API theme
KindlySDK.clearCustomTheme() // Reverts to API or default theme
// Set custom theme again (overrides API theme)
KindlySDK.setCustomTheme(background: UIColor.white)Live Theme Updates
setCustomTheme(...) and clearCustomTheme() apply immediately to a chat that is currently on screen. There is no need to dismiss and re-display the chat for the new colors to take effect. The page background, navigation bar, message bubbles, system messages, typing indicator, attachments, image cells, form cells, action buttons, file-upload labels, the input field, and the toolbar all refresh in place.
This makes it natural to swap themes in response to system appearance changes. For example, observe traitCollectionDidChange in your host view controller and call setCustomTheme(...) again with a dark or light palette:
override func traitCollectionDidChange(_ previousTraitCollection: UITraitCollection?) {
super.traitCollectionDidChange(previousTraitCollection)
let isDark = traitCollection.userInterfaceStyle == .dark
KindlySDK.setCustomTheme(
background: isDark ? .black : .white,
botMessageBackground: isDark ? UIColor(white: 0.18, alpha: 1) : UIColor(white: 0.95, alpha: 1),
// ... etc
)
}Internally the SDK posts a Notification.Name.kindlyThemeDidChange notification on every theme update; views in the chat hierarchy observe it and re-apply theme-derived colors. The notification is public, so host apps can also subscribe if they need to react to theme changes themselves.