Edit

Theme the UI Library in an application

  • Article

The Azure Communication Services UI Library is a set of components, icons, and composites that make it easier for you to build high-quality user interfaces for your projects. The UI Library uses components and icons from Fluent UI, the cross-platform design system that Microsoft uses. As a result, the components are built with usability, accessibility, and localization in mind.

In this article, you learn how to change the theme for UI Library components as you configure an application.

The UI Library is fully documented for developers on a separate site. The documentation is interactive and helps you understand how the APIs work by giving you the ability to try them directly from a webpage. For more information, see the UI Library documentation.

Prerequisites

Set up theming

For detailed documentation and quickstarts about the Web UI Library, see the Web UI Library Storybook.

To learn more, see Theming in the Web UI Library.

For more information, see the open-source Android UI Library and the sample application code.

Defining a theme

Theming on Android is handled via XML resource files. We expose the following resource IDs to the public scope:

<resources>
    <public name="AzureCommunicationUICalling.Theme" type="style" />
    <public name="azure_communication_ui_calling_primary_color" type="attr" />
    <public name="azure_communication_ui_calling_primary_color_tint10" type="attr" />
    <public name="azure_communication_ui_calling_primary_color_tint20" type="attr" />
    <public name="azure_communication_ui_calling_primary_color_tint30" type="attr" />
</resources>

You can implement a theme like the following one in your apps to supply the primary color and tints:

<style name="MyCompany.CallComposite" parent="AzureCommunicationUICalling.Theme">
    <item name="azure_communication_ui_calling_primary_color">#7800D4</item>
    <item name="azure_communication_ui_calling_primary_color_tint10">#882BD8</item>
    <item name="azure_communication_ui_calling_primary_color_tint20">#E0C7F4</item>
    <item name="azure_communication_ui_calling_primary_color_tint30">#ECDEF9</item>
</style>

The preceding example affects the following UI elements:

  • PrimaryColor:
    • Avatar/Video - Border - Speaking Indication
    • Join Call Button - Background
  • PrimaryColorTint10 Color:
    • Join Call Button - Background - Highlighted - Light Mode
    • Join Call Button - Border - Light/Dark Mode
  • PrimaryColorTint20 Color:
    • Join Call Button - Background - Highlighted - Dark Mode
  • PrimaryColorTint30 Color:
    • Join Call Button - Border - Highlighted - Light/Dark Mode

Applying a theme

The theme style is applied to pass the theme resource ID to ThemeConfiguration/Theme in CallCompositeBuilder.

val callComposite: CallComposite =
        CallCompositeBuilder()
            .theme(R.style.MyCompany_CallComposite)
            .build()

Light and dark modes

The Android resource system handles the night theme. Night mode on Android is a system-wide configuration. When you enable night mode, Android gives preference to resources in the -night/ folders. To specify night mode colors, add a second theme.xml file to values-night/.

To enable night mode programmatically, Android provides the following function. However, this configuration applies globally to the application. There's no reliable way to set night mode for a single activity. To enforce a dark theme, use the following setting in your applications:

AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)

For more information, see the open-source iOS UI Library and the sample application code.

Defining a theme

You can customize the theme by changing the primary color and its associated tints. You also have the option of overriding the light and dark modes in the color scheme.

Affected UI

  • PrimaryColor:
    • Avatar/Video - Border - Speaking Indication
    • Join Call Button - Background
  • PrimaryColorTint10 Color:
    • Join Call Button - Background - Highlighted - Light Mode
    • Join Call Button - Border - Light/Dark Mode
  • PrimaryColorTint20 Color:
    • Join Call Button - Background - Highlighted - Dark Mode
  • PrimaryColorTint30 Color:
    • Join Call Button - Border - Highlighted - Light/Dark Mode

Implementation

You can create custom theme options that implement the ThemeOptions protocol. You need to include an instance of that new class in CallCompositeOptions.

class CustomThemeOptions: ThemeOptions {

 var primaryColor: UIColor {
  return UIColor(named: "primaryColor")
 }
 
 var primaryColorTint10: UIColor {
  return UIColor(named: "primaryColorTint10")
 }
 
 var primaryColorTint20: UIColor {
  return UIColor(named: "primaryColorTint20")
 }
 
 var primaryColorTint30: UIColor {
  return UIColor(named: "primaryColorTint30")
 }

 var colorSchemeOverride: UIUserInterfaceStyle {
  return UIUserInterfaceStyle.dark
 }
}

let callCompositeOptions = CallCompositeOptions(theme: CustomThemeOptions())

Defining color assets

Define each color in the assets, with a shade for the light and dark modes. The following reference image shows how to configure the assets on an Xcode project.

Screenshot of an example configuration of iOS color assets.

Next steps