Theming

The Persona React Native SDK relies on theming capabilities provided by underlying native platforms to ensure that themes run smoothly and have no negative impact on the overall performance and user experience.

📘

Platform differences

Because Android and iOS look and feel customization are pretty different, there are discrepancies to consider when theming each platform. We recommend tackling theming on each platform separately.

🚧

Camera screens are not themeable

Camera screens are not theme-able on iOS since they contain core functionality that needs to work a certain way.

While Android has native mechanisms for styling the Camera screen, we highly recommend against it.

Using the built-in CLI tool

The React Native Persona SDK comes with a built-in CLI tool that aims to help you work with the native theming capabilities supported on Android and iOS.

Run persona-tool

# with yarn
yarn persona-tool

# with npx
npx persona-tool

Follow the instructions to configure the tool. Copy the configuration snippet into your application's package.json. As of 2021-12-07 it looks something like this:

  "persona": {
    "androidTheme": {
      "backgroundColor": null,
      "primaryColor": null,
      "darkPrimaryColor": null,
      "accentColor": null,
      "progressColor": null,
      "titleTextColor": null,
      "titleTextFont": null,
      "titleTextSize": null,
      "bodyTextColor": null,
      "bodyTextFont": null,
      "bodyTextSize": null,
      "footnoteTextColor": null,
      "footnoteTextFont": null,
      "footnoteTextSize": null,
      "textFieldTextColor": null,
      "textFieldTextFont": null,
      "pickerTextColor": null,
      "pickerTextFont": null,
      "cameraInstructionsTextColor": null,
      "cameraInstructionsTextFont": null,
      "cameraInstructionsTextSize": null,
      "cameraHintTextColor": null,
      "cameraHintTextFont": null,
      "cameraHintTextSize": null,
      "cameraGuideHintTextColor": null,
      "cameraGuideHintTextFont": null,
      "cameraGuideHintTextSize": null,
      "buttonBackgroundColor": null,
      "buttonDisabledBackgroundColor": null,
      "buttonTouchedBackgroundColor": null,
      "buttonTextColor": null,
      "buttonDisabledTextColor": null,
      "buttonCornerRadius": null,
      "buttonFont": null,
      "buttonTextSize": null,
      "successAsset": null,
      "failAsset": null,
      "loadingAnimationAsset": null,
      "loadingAnimationWidthPercent": null,
      "selfieAnimationAsset": null,
      "selfieAnimationWidthPercent": null
    },
    "iosTheme": {
      "backgroundColor": null,
      "primaryColor": null,
      "darkPrimaryColor": null,
      "accentColor": null,
      "progressColor": null,
      "overlayBackgroundColor": null,
      "titleTextColor": null,
      "titleTextFont": null,
      "titleTextSize": null,
      "titleTextAlignment": null,
      "bodyTextColor": null,
      "bodyTextFont": null,
      "bodyTextSize": null,
      "bodyTextAlignment": null,
      "footnoteTextColor": null,
      "footnoteTextFont": null,
      "footnoteTextSize": null,
      "formLabelTextColor": null,
      "formLabelTextFont": null,
      "textFieldTextColor": null,
      "textFieldBackgroundColor": null,
      "textFieldBorderColor": null,
      "pickerTextColor": null,
      "pickerTextFont": null,
      "cameraInstructionsTextColor": null,
      "cameraInstructionsTextFont": null,
      "cameraInstructionsTextSize": null,
      "cameraHintTextColor": null,
      "cameraHintTextFont": null,
      "cameraHintTextSize": null,
      "cameraGuideHintTextColor": null,
      "cameraGuideHintTextFont": null,
      "cameraGuideHintTextSize": null,
      "buttonBackgroundColor": null,
      "buttonDisabledBackgroundColor": null,
      "buttonTouchedBackgroundColor": null,
      "buttonImageTintColor": null,
      "buttonImageHidden": null,
      "buttonCornerRadius": null,
      "buttonTextAlignment": null,
      "buttonDisabledTextColor": null,
      "buttonTextColor": null,
      "buttonFont": null,
      "buttonTextSize": null,
      "selectedCellBackgroundColor": null,
      "closeButtonTintColor": null,
      "cancelButtonBackgroundColor": null,
      "cameraButtonBackgroundColor": null,
      "cameraGuideCornersColor": null,
      "successAssetName": null,
      "successAssetWidth": null,
      "successAssetHeight": null,
      "verificationFailAssetName": null,
      "verificationFailAssetWidth": null,
      "verificationFailAssetHeight": null,
      "failAssetName": null,
      "failAssetWidth": null,
      "failAssetHeight": null,
      "loadingAnimationAssetName": null,
      "loadingAnimationAssetWidth": null,
      "loadingAnimationAssetHeight": null,
      "processingAnimationAssetName": null,
      "processingAnimationAssetWidth": null,
      "processingAnimationAssetHeight": null,
      "selfieAnimationAssetName": null,
      "selfieAnimationAssetWidth": null,
      "selfieAnimationAssetHeight": null
    }
  }

Colors

Optionally modify the color values to valid hexadecimal color codes. Examples: #0000FF, 4700EB.

Fonts

Optionally modify the font values to font names that are either built-in to the platform or have been built into your application. Examples: sans-serif (Android), San Francisco (iOS), @font/customira (Android custom).

For the smoothest installation and overall experience, we recommend sticking with system defaults, but if font change is desired, view additional information in Customizing Fonts on iOS and Customizing Fonts on Android.

You can also update the font sizes. Simply supply a number value as a string and the theming tool will convert it to the proper units for the respective platforms, e.g:

"titleTextSize": "48",
"bodyTextSize": "14",

Images & Animations

Optionally modify the asset values to provide assets and dimensions from your project to override the defaults found in the Persona flow. The image asset overrides need to be .svg files and the animation asset overrides should be .json files compatible with the Lottie animation library.

iOS requires the asset name and dimensions:

 "successAssetName": "customSuccessImage",
 "successAssetWidth": "60",
 "successAssetHeight": "60",

Android requires just the resource path:

"successAsset": "@drawable/custom_success_image`

After modifying, run persona-tool again and select either Update iOS Theme or Update Android theme. If you want to do both, you have to run this tool twice.

• Updating the iOS theme should print further instructions to pass the theme into the Inquiry client.
• Updating the Android theme should generate style, color, and drawable resource files into your Android project's res directory.

Callouts for Android

• The pickerTextColor and pickerTextFont theme keys style Android's Spinner components.

What to theme first.

To get started with theming, we recommend starting with the main colors: backgroundColor, primaryColor, darkPrimaryColor, and accentColor, and the textColors.

After these match your brand's colors, you can tweak individual elements as desired.

What to theme next on Android

After theming the core colors, you can theme text fields, picker (spinner)s, and buttons. Text fields and pickers may not show up within your template, so they may be irrelevant for your integration. Text fields and pickers should look similar since they are form controls.

What to theme next on iOS

iOS has an additional overlayBackgroundColor that determines the background color of the Toast element that pops up if an individual decides to cancel. This option is not available on Android as the component does not exist.

After theming the core colors, you can theme text fields, pickers, and buttons. Text fields and pickers may not show up within your template, so they may be irrelevant for your integration. Text fields and pickers should look similar since they are form controls.

selectedCellBackgroundColor determines the color of the cells in the country picker (may not exist in your template)

closeButtonTintColor determines the color of the "x" to close the Inquiry flow should an individual choose not to complete. This close button opens the cancel toast element.

cancelButtonBackgroundColor determines the color of the cancel button within the cancel toast element.

Customizing Fonts on Android

In order to specify fonts on Android, the fonts either must be system fonts or fonts bundled into your application. For a list of system fonts available out of the box, view: https://github.com/react-native-training/react-native-fonts#android.

As an example, If you want to use sans-serif-medium on Android, then setpersona.androidTheme.titleTextFont:

"persona": {
  "androidTheme": {
    "titleTextFont": "sans-serif-medium"
  }
}

Providing a custom font

If you would like to provide your own custom font, first create a font resource by following the follow guide: https://developer.android.com/guide/topics/ui/look-and-feel/fonts-in-xml.

"persona": {
  "androidTheme": {
    "titleTextFont": "@font/custom-font"
  }
}

Customizing Fonts on iOS

In order to specify fonts on iOS, the fonts must be either system fonts or fonts bundled into your application. For a list of system fonts available out of the box, view: https://github.com/react-native-training/react-native-fonts#ios

Providing a custom font

If you would like to provide your own custom font, add a font file to the Xcode project by following the guide here: https://developer.apple.com/documentation/uikit/text_display_and_fonts/adding_a_custom_font_to_your_app.

Then, you can specify your custom font.

"persona": {
  "iosTheme": {
    "titleTextFont": "CustomFont-light"
  }
}