Theme customization

Chat UI SDK for Android uses ChatUIThemeManager to manage built-in and custom themes. The SDK currently provides the built-in LIVELY_THEME, supports light/dark style variants, and can switch themes at runtime.

How themes work

• NCChatUI.initialize(...) initializes the theme system through NCChatUIConfig.syncFromXml(...).
• The built-in ChatUIThemeManager.LIVELY_THEME follows the active light/dark mode.
• Custom themes are registered with one light style and one dark style.
• A custom theme can be stacked on top of a base theme, so unspecified attributes fall back to the base theme.
• Existing and future Activities can be updated after a theme switch. Recreate the current Activity if your custom page does not refresh automatically.

Register a custom theme

Define light and dark style resources in your app. Override only the Chat UI attributes that you need to change.

xml

res/values/styles.xml

<style name="MyCustomLightTheme">
    <item name="nc_primary_color">@color/my_primary_color</item>
    <item name="nc_common_background_color">@color/my_background_color</item>
    <item name="nc_text_primary_color">@color/my_text_primary_color</item>
</style>

xml

res/values-night/styles.xml

<style name="MyCustomDarkTheme">
    <item name="nc_primary_color">@color/my_primary_color_dark</item>
    <item name="nc_common_background_color">@color/my_background_color_dark</item>
    <item name="nc_text_primary_color">@color/my_text_primary_color_dark</item>
</style>

Register the theme before switching to it.

Kotlin

kotlin

import ai.nexconn.chat.params.InitParams
import ai.nexconn.chatui.NCChatUI
import ai.nexconn.chatui.config.ChatUIThemeManager
import android.app.Application

class App : Application() {
    override fun onCreate() {
        super.onCreate()

        ChatUIThemeManager.addTheme(
            "CUSTOM_BLUE_THEME",
            R.style.MyCustomLightTheme,
            R.style.MyCustomDarkTheme,
        )

        NCChatUI.initialize(InitParams(this, "your-app-key"))
    }
}

Java

Java

import ai.nexconn.chat.params.InitParams;
import ai.nexconn.chatui.NCChatUI;
import ai.nexconn.chatui.config.ChatUIThemeManager;
import android.app.Application;

public class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        ChatUIThemeManager.addTheme(
                "CUSTOM_BLUE_THEME",
                R.style.MyCustomLightTheme,
                R.style.MyCustomDarkTheme);

        NCChatUI.initialize(new InitParams(this, "your-app-key"));
    }
}

Switch themes

Use changeInnerTheme(...) for built-in themes and changeCustomTheme(...) for custom themes.

Kotlin

kotlin

// Switch to the built-in Lively theme.
ChatUIThemeManager.changeInnerTheme(this, ChatUIThemeManager.LIVELY_THEME)

// Switch to a custom theme based on the built-in Lively theme.
ChatUIThemeManager.changeCustomTheme(
    this,
    "CUSTOM_BLUE_THEME",
    ChatUIThemeManager.LIVELY_THEME,
)

Java

Java

// Switch to the built-in Lively theme.
ChatUIThemeManager.changeInnerTheme(this, ChatUIThemeManager.LIVELY_THEME);

// Switch to a custom theme based on the built-in Lively theme.
ChatUIThemeManager.changeCustomTheme(
        this,
        "CUSTOM_BLUE_THEME",
        ChatUIThemeManager.LIVELY_THEME);

Follow light and dark mode

If your app uses AppCompat, set the default night mode early in Application.onCreate().

Kotlin

kotlin

AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_FOLLOW_SYSTEM)

Java

Java

AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_FOLLOW_SYSTEM);

Listen for theme changes

Register a listener if your custom UI needs to refresh immediately after a theme switch.

Kotlin

kotlin

val listener = ChatUIThemeManager.OnThemeListener { context, _, _ ->
    (context as? Activity)?.recreate()
}

ChatUIThemeManager.addThemeListener(listener)

// Remove it when no longer needed.
ChatUIThemeManager.removeThemeListener(listener)

Java

Java

ChatUIThemeManager.OnThemeListener listener =
        (context, oldTheme, newTheme) -> {
            if (context instanceof Activity) {
                ((Activity) context).recreate();
            }
        };

ChatUIThemeManager.addThemeListener(listener);

// Remove it when no longer needed.
ChatUIThemeManager.removeThemeListener(listener);

Resolve theme attributes

Use the active theme to resolve Chat UI attributes when drawing custom views.

Kotlin

kotlin

val backgroundResId = ChatUIThemeManager.getAttrResId(
    context,
    R.attr.nc_common_background_color,
)
view.setBackgroundResource(backgroundResId)

val primaryColor = ChatUIThemeManager.getColorFromAttrId(
    context,
    R.attr.nc_primary_color,
)

Java

Java

int backgroundResId = ChatUIThemeManager.getAttrResId(
        context,
        R.attr.nc_common_background_color);
view.setBackgroundResource(backgroundResId);

int primaryColor = ChatUIThemeManager.getColorFromAttrId(
        context,
        R.attr.nc_primary_color);