Many aspects of the UI components can be changed and customized. For example, it's possible to change:

Colors
Text appearances
Backgrounds of views
Icons

Use a Material3 theme

All Nabla UI components will inherit the theme you specify for their container, this is usually the Application or Activity’s theme.

📘
The theme should inherit from Theme.Material3.* by Material3 for Nabla UI components to behave correctly.

Customize global colors, icons, backgrounds, and text appearances

Nabla UI components will, by default, use the provided Material3 theme attributes to give a coherent look with the rest of your app. Thus, you can rely on attributes like colorPrimary, colorSurface, colorError, toolbarStyle or textAppearanceBodyMedium to act as a central source of theming for both your app UI components and Nabla ones.

Here's a complete example of how to build a theme that Nabla UI components will use with Material3 attributes:

<style name="Theme.Example.Blue" parent="Theme.Material3.Light.NoActionBar">
    <item name="android:colorBackground">#FFF</item>
    <item name="colorPrimary">#007AFF</item>
    <item name="colorOnPrimary">#FFFFFF</item>
    <item name="android:textColorPrimary">#26282D</item>
    <item name="android:textColorSecondary">@color/black</item>
    <item name="colorSurface">#FFFFFF</item>
    <item name="colorOnSurface">#7F879E</item>
    <item name="colorSurfaceVariant">#F1F4F9</item>
    <item name="colorControlHighlight">#1F6F787E</item>
    <item name="colorOutline">#DADADA</item>
    <item name="colorPrimaryContainer">#007AFF</item>
    <item name="colorOnPrimaryContainer">#FFFFFF</item>

    <item name="textAppearanceBodyMedium">@style/TextAppearance.Example.BodyMedium</item>
    <item name="materialButtonStyle">@style/Widget.Example.Button</item>
    <item name="materialButtonOutlinedStyle">@style/Widget.Example.Button.OutlinedButton</item>
    <item name="toolbarStyle">@style/Widget.Example.Toolbar</item>
    <item name="toolbarSurfaceStyle">@style/Widget.Example.Toolbar.Surface</item>
</style>

<style name="TextAppearance.Example.BodyMedium" parent="TextAppearance.Material3.BodyMedium">
    <item name="android:textColor">?android:textColorSecondary</item>
</style>

<style name="Widget.Example.Button" parent="Widget.Material3.Button">
    <item name="shapeAppearanceOverlay">@style/ShapeAppearanceOverlay.Example.Button</item>
    <item name="android:paddingTop">14dp</item>
    <item name="android:paddingBottom">14dp</item>
    <item name="android:textAppearance">?textAppearanceTitleMedium</item>
</style>

<style name="Widget.Example.Toolbar" parent="Widget.Material3.Toolbar">
    <item name="titleTextAppearance">?textAppearanceTitleMedium</item>
</style>

<style name="Widget.Example.Toolbar.Surface">
    <item name="android:background">?attr/colorSurface</item>
</style>

<style name="Widget.Example.Button.OutlinedButton" parent="Widget.Material3.Button.OutlinedButton">
    <item name="android:paddingTop">14dp</item>
    <item name="android:paddingBottom">14dp</item>
    <item name="strokeColor">?colorPrimary</item>
    <item name="android:textAppearance">?textAppearanceTitleMedium</item>
</style>

Nabla specific theme attributes

In addition to Material3 theme attributes, Nabla UI components have some specific theme attributes to play with:

nablaAvatarViewStyle to customize how avatars are rendered. You can change:
- nabla_clipShape: shape of the avatar (roundRect, oval or none: square), defaults to oval.
- nabla_useSingleLetterInPlaceHolder: Given that placeholder for when a user has no avatar is their initials, this is to choose whether to use only the last name (single letter) or both first and last names (two letters). Defaults to true.
- nabla_defaultBackgroundColor: color of the background displayed when no avatar is available, defaults to colorSurfaceVariant.
- nabla_defaultAvatarDrawable: default drawable used when no picture or abbreviated name are available, defaults to nabla_ic_outline_person.xml
nablaRoundedCornersRadius to customize the corner radius used in many components like Messaging message's bubble shape or conversations list item background.

Here's how you can use them:

<style name="Theme.Example.Blue" parent="Theme.Material3.Light.NoActionBar">
    <!-- Rest of your theme -->

    <item name="nablaAvatarViewStyle">@style/NablaOverlay.Example.AvatarView</item>
    <item name="nablaRoundedCornersRadius">16dp</item>
</style>

<style name="NablaOverlay.Example.AvatarView" parent="Nabla.Widget.AvatarView">
    <item name="nabla_clipShape">roundRect</item>
</style>

How Nabla UI components will adopt your app theme

Main elements of the UI provided by Nabla have customization attributes you can specify in your theme, e.g. nablaMessaging_patientMessageBackgroundColor (see Module-specific theming for the exhaustive list).
Fortunately, you will rarely need to go that specific in your theme attributes. In fact, if not specified, each of these attributes will fallback to a Material3 attribute.
Therefore, specifying only the Material3 generic attributes (e.g. colorPrimary, colorOnPrimary, textAppearanceBodyMedium, materialButtonStyle, etc) might be enough.

Here's an example of how UI elements will end up picking their attributes, if your app uses the Theme.Example.Blue from above.

nablaMessaging_conversationHeaderTitleAppearance → textAppearanceTitleMedium → @style/TextAppearance.Material3.TitleMedium (inherited from Theme.Material3.Light.NoActionBar) → Bold 16sp with text color referencing android:textColorPrimary → #26282D
nablaMessaging_conversationHeaderSubtitleAppearance → textAppearanceBodyMedium → @style/TextAppearance.Example.BodyMedium → with text color referencing android:textColorSecondary → #6F787E
nablaMessaging_conversationHeaderStyle → toolbarSurfaceStyle → @style/Widget.Example.Toolbar.Surface
nablaMessaging_conversationBackgroundColor → android:colorBackground → #F1F4F9
nablaMessaging_patientMessageBackgroundColor → colorPrimary → #007AFF
nablaMessaging_conversationPatientMessageAppearance → @style/Nabla.TextAppearance.TextMessage.Patient with text color referencing colorOnPrimary → #FFFFFF
Color of all other elements (play button, loading spinner for images, etc.) drawn on patient message bubble infer their color from the text appearance in (6) → ... → #FFFFFF
nablaMessaging_conversationProviderMessageAppearance → @style/Nabla.TextAppearance.TextMessage.Provider with text color referencing colorPrimary → #007AFF
nablaMessaging_providerMessageBackgroundColor → colorSurface → #FFFFFF
Similar to (7): Color of all other elements (in this case: pdf icon and replied-message indent) drawn on provider message bubble infer their color from the text appearance in (8) → ... → #007AFF
nablaMessaging_conversationRepliedMessageAuthorAppearance with text color set similarly to (10) → textAppearanceTitleSmall → @style/TextAppearance.Material3.TitleSmall → bold 14sp
nablaMessaging_conversationMessageAuthorAppearance → textAppearanceBodyMedium → @style/TextAppearance.Example.BodyMedium → with text color referencing android:textColorSecondary → #6F787E
nablaAvatarViewStyle → @style/Nabla.Widget.AvatarView → circular outline shape, single letter for placeholder, etc.
nablaMessaging_addMediaIcon → @drawable/nabla_ic_add → vector drawable with a tint of colorOnSurface.
nablaMessaging_conversationComposerEditTextStyle → @style/Nabla.Widget.Messaging.ComposerEditTextStyle → @style/Widget.AppCompat.EditText + text appearance to textAppearanceBodyLarge, hint text color to colorOnSurface, etc.

Dark mode support

Thanks to the theme abstractions explained previously, supporting dark mode is actually out-of-the-box.

For instance, if your app declares a dark mode theme (in your values-night) where it alters its Theme.Example.Blue light mode theme colors as follows.

<style name="Theme.Example.Blue.Night">
    <item name="android:colorBackground">#000</item>
    <item name="colorPrimary">#ADC7F7</item>
    <item name="colorOnPrimary">#000000</item>
    <item name="android:textColorPrimary">#FFFFFF</item>
    <item name="android:textColorSecondary">@color/white</item>
    <item name="colorSurface">#252A30</item>
    <item name="colorOnSurface">#FFFFFF</item>
    <item name="colorSurfaceVariant">#40484D</item>
    <item name="colorControlHighlight">#33FFFFFF</item>
    <item name="colorOutline">#6F787E</item>
    <item name="colorPrimaryContainer">#ADC7F7</item>
    <item name="colorOnPrimaryContainer">#000000</item>

    <item name="android:statusBarColor">?colorSurface</item>
</style>

Then the Conversation screen from above will show in dark mode.

Module-specific theming

You can find module-specific theme attributes in their own section: