Customizing the UI

The Zendesk SDK UI can be styled to match your brand using the UserColors API, which provides developers with a robust way to customize the colors of specific UI components in the SDK. This API allows you to define custom colors for elements such as text on buttons, messages, and actions, ensuring your app's UI aligns with your brand identity.

With support for both light and dark mode, the UserColors API ensures that your UI remains visually consistent and accessible across different themes. Use this API to override default colors and deliver a tailored user experience.

Customize colors using UserColors

Below are the colors that can be customized directly within you app,letting you match the app’s look with your brand colors. This level of customization supports both light and dark modes

Property	Description
primary	Background color of the headers on the conversation screen and the conversation list screen.
onPrimary	Text and icon color on primary backgrounds.
message	Background color for end-user messages.
onMessage	Text and icon color on message backgrounds.
businessMessage	Background color for business messages (messages from the business or agents).
onBusinessMessage	Text and icon color on business message backgrounds.
action	Background color for action buttons such as new conversation, carousel buttons, form button.
onAction	Text and icon color on action backgrounds.
background	Background color of the conversation screen and conversation list screen.
onBackground	Color for descriptive elements on background (timestamps, names, message status), with 65% opacity
error	Background color for alert elements such as failed messages or upload errors.
onError	Text and icon color on error backgrounds.
notify	Color for unread message badges.
onNotify	Text and icon color on notify backgrounds.
onSecondaryAction	Color of the Quick reply text and border, composer focused border and send button.

Customizing colors using Admin Center

If primary, message, or action colors are not provided through the UserColors API, the SDK will use the colors configured in Admin Center.

Property	Default Color
primary	Admin Center primary color
message	Admin Center message color
action	Admin Center action color

UserColors API

To customize colors, use the UserColors API when initializing the SDK. This allows you to set colors for light and dark mode.

Kotlin

val userLightColors = UserColors(
    primary = Color.CYAN,
    onPrimary = Color.RED,
    action = Color.BLUE,
    onAction = Color.RED,
    onMessage = Color.RED,
    message = Color.CYAN,
    onBusinessMessage = Color.GREEN,
    businessMessage = Color.BLUE,
    background = Color.GRAY,
    onBackground = Color.BLUE,
    onSecondaryAction = Color.MAGENTA,
    error = Color.YELLOW,
    notify = Color.GREEN,
    onError = Color.RED,
    onNotify = Color.YELLOW,
)

val userDarkColors = UserColors(
    primary = Color.CYAN,
    onPrimary = Color.YELLOW,
    action = Color.BLUE,
    onAction = Color.YELLOW,
    onMessage = Color.YELLOW,
    message = Color.CYAN,
    onBusinessMessage = Color.GREEN,
    businessMessage = Color.BLUE,
    background = Color.GRAY,
    onBackground = Color.BLUE,
    onSecondaryAction = Color.MAGENTA,
    error = Color.YELLOW,
    notify = Color.GREEN,
    onError = Color.RED,
    onNotify = Color.YELLOW,
)
val factory = DefaultMessagingFactory(
    userLightColors = userLightColors,
    userDarkColors = userDarkColors,
)
Zendesk.initialize(
    context = this,
    channelKey = "channel_key",
    messagingFactory = factory,
)

Java

import java.awt.Color;

UserColors userLightColors = new UserColors(Color.BLACK, Color.BLACK, Color.BLACK);
UserColors userDarkColors = new UserColors(Color.WHITE,Color.WHITE,Color.WHITE);
DefaultMessagingFactory factory = new DefaultMessagingFactory(userLightColors, userDarkColors);
Zendesk.

initialize(this,"channel_key",factory);

FAQ

Q: Can I customize all UI colors in Admin Center?
A: No. Only primary, message bubble, and action button colors are customizable in Admin Center. Text colors and some secondary UI elements must be set using the SDK’s UserColors API.

Q: What happens if I set text colors in Admin Center?
A: Text colors cannot be overridden in Admin Center. You must use the UserColors API in your app code to change them.

Q: How do I support both light and dark mode for text colors?
A: Pass different UserColors objects for userLightColors and userDarkColors when initializing the SDK.

Q: What if I don’t set text colors using UserColors?
A: The SDK will use its default text colors, which may not match your brand or accessibility requirements.