Theming

Apply your app theme to the Nabla SDK

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="backgroundColor">#F1F4F9</item>
    <item name="android:colorBackground">#F1F4F9</item>
    <item name="colorPrimary">#007AFF</item>
    <item name="colorPrimaryContainer">#007AFF</item>
    <item name="android:textColorPrimary">#26282D</item>
    <item name="android:textColorSecondary">#6F787E</item>
    <item name="colorOnSurface">#7F879E</item>
    <item name="colorSurface">#FFFFFF</item>
    <item name="colorOnPrimary">#FFFFFF</item>
    <item name="colorOnPrimaryContainer">#FFFFFF</item>
    <item name="colorControlHighlight">#1F6F787E</item>
    <item name="strokeColor">#DADADA</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 colorPrimary.
  • 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/Nabla.Widget.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.

example app screenshot with numbered elementsexample app screenshot with numbered elements
  1. nablaMessaging_conversationHeaderTitleAppearance β†’ textAppearanceTitleMedium β†’ @style/TextAppearance.Material3.TitleMedium (inherited from Theme.Material3.Light.NoActionBar) β†’ Bold 16sp with text color referencing android:textColorPrimary β†’ #26282D
  2. nablaMessaging_conversationHeaderSubtitleAppearance β†’ textAppearanceBodyMedium β†’ @style/TextAppearance.Example.BodyMedium β†’ with text color referencing android:textColorSecondary β†’ #6F787E
  3. nablaMessaging_conversationHeaderStyle β†’ toolbarSurfaceStyle β†’ @style/Widget.Example.Toolbar.Surface
  4. nablaMessaging_conversationBackgroundColor β†’ android:colorBackground β†’ #F1F4F9
  5. nablaMessaging_patientMessageBackgroundColor β†’ colorPrimaryDark β†’ colorPrimary β†’ #007AFF
  6. nablaMessaging_conversationPatientMessageAppearance β†’ @style/Nabla.TextAppearance.TextMessage.Patient with text color referencing colorOnPrimary β†’ #FFFFFF
  7. 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
  8. nablaMessaging_conversationProviderMessageAppearance β†’ @style/Nabla.TextAppearance.TextMessage.Provider with text color referencing colorPrimaryDark β†’ #007AFF
  9. nablaMessaging_providerMessageBackgroundColor β†’ colorSurface β†’ #FFFFFF
  10. 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
  11. nablaMessaging_conversationRepliedMessageAuthorAppearance with text color set similarly to (10) β†’ textAppearanceTitleSmall β†’ @style/TextAppearance.Material3.TitleSmall β†’ bold 14sp
  12. nablaMessaging_conversationMessageAuthorAppearance β†’ textAppearanceBodyMedium β†’ @style/TextAppearance.Example.BodyMedium β†’ with text color referencing android:textColorSecondary β†’ #6F787E
  13. nablaAvatarViewStyle β†’ @style/Nabla.Widget.AvatarView β†’ circular outline shape, single letter for placeholder, etc.
  14. nablaMessaging_addMediaIcon β†’ @drawable/nabla_ic_add β†’ vector drawable with a tint of colorOnSurface.
  15. nablaMessaging_conversationComposerEditTextStyle β†’ @style/Nabla.Widget.Messaging.ComposerEditTextStyle β†’ @style/Widget.AppCompat.EditText + text appearance to textAppearanceBodyLarge, hint text color to colorOnSurface, etc.

Dark mode support

example app screenshot in dark modeexample app screenshot in dark mode

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="backgroundColor">#000000</item>
    <item name="android:colorBackground">#000</item>
    <item name="colorPrimary">#ADC7F7</item>
    <item name="colorPrimaryContainer">#ADC7F7</item>
    <item name="android:textColorPrimary">#FFFFFF</item>
    <item name="android:textColorSecondary">#FFFFFF</item>
    <item name="colorOnSurface">#FFFFFF</item>
    <item name="colorSurface">#252A30</item>
    <item name="colorOnPrimary">#000000</item>
    <item name="colorOnPrimaryContainer">#000000</item>
    <item name="colorControlHighlight">#33FFFFFF</item>
    <item name="strokeColor">#6F787E</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: