React Native SDK v1 Theming
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
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
andpickerTextFont
theme keys style Android'sSpinner
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"
}
}
Updated 12 months ago