Customizing PDF viewer styling on Android

To customize UI elements, Nutrient uses the standard Android style and theme system(opens in a new tab). When declaring a theme for your application, you can define the primary colors using the attributes colorPrimary, colorSecondary, colorAccent, and colorPrimaryDark. All UI components of Nutrient (toolbars, views, dialogs, etc.) will use these colors to style the rest of the UI.

Out of the box, Nutrient comes with two predefined themes — PSPDFKit.Theme.Default and PSPDFKit.Theme.Dark — for the PdfActivity and all of its views. This guide describes how to tweak the default appearance to match the look of your app.

Defining a custom theme

Since Nutrient adheres to Android’s style and theme framework, you have full control over styling the appearance of all Nutrient components. The PdfActivity is built on top of the Android Compatibility Library v7 and MaterialComponents, which means your theme has to inherit from Theme.MaterialComponents.

Furthermore, since PdfActivity uses a custom toolbar system, the decor action bar of the activity has to be deactivated. The easiest way to do this is to use the default Nutrient themes (PSPDFKit.Theme.Default and PSPDFKit.Theme.Dark) or Theme.MaterialComponents.NoActionBar as a parent theme.

1. Inside your app’s styles.xml, create a custom theme with Theme.MaterialComponents.NoActionBar as the parent. Or, to tweak the default style, a custom theme can inherit directly from PSPDFKit.Theme.Default or PSPDFKit.Theme.Dark as a parent:

   <style name="MyApp.PSPDFKitTheme" parent="PSPDFKit.Theme.Default">
       <item name="colorPrimary">@color/mymain_color</item>
       <item name="colorPrimaryDark">@color/mymain_color_dark</item>
       <item name="colorSecondary">@color/mymain_color_secondary</item>
       <item name="colorAccent">@color/mymain_color_accent</item>
   
       <!-- Nutrient comes with several styleable components. -->
       <item name="pspdf__inlineSearchStyle">@style/MyInlineSearch</item>
   </style>
   
   <style name="MyInlineSearch">
       <item name="pspdf__textColor">@color/my_inline_search_color</item>
   </style>

   If you want to use a different parent theme, you can manually disable the default window decor action bar by setting windowActionBar to false and windowNoTitle to true.

2. Next, set your theme to the PdfActivity using the android:theme property inside your AndroidManifest.xml:

   <application>
       <activity android:name="com.pspdfkit.ui.PdfActivity"
                 android:theme="@style/MyApp.PSPDFKitTheme"/>
   </application>

A custom theme can be set either using the manifest or via PdfActivityConfiguration#Builder. In default mode, it can be set via PdfActivityConfiguration.Builder#theme(int), while in night theme mode, it can be set via PdfActivityConfiguration.Builder#themeDark(int). When a custom theme is set using the builder configuration, it overwrites the custom theme set in the manifest.

Nutrient resolves the used style values in the following order, using the first style found:

1. Styles provided by the custom theme (i.e. your MyApp.PSPDFKitTheme in the above example) set in the manifest for com.pspdfkit.ui.PdfActivity.
2. Default styles/internal Nutrient styles.

This means that Nutrient will use default values for all styles not covered under the current theme’s customization.

Available styles

Nutrient provides a large set of style attributes for both default and dark themes. This allows you to alter the appearance according to your needs. For a comprehensive usage example, have a look at DarkThemeExample and DarkThemeActivity inside the Catalog app.

Navigation history buttons styling

If you want to tweak the default appearance of the chevron icon color inside the navigation history buttons, you can use the pspdf__navigationHistoryIconColor attribute:

<style name="MyApp.Theme" parent="Theme.MaterialComponents.Light.NoActionBar">
    <item name="pspdf__navigationHistoryIconColor">@color/dark_icons_blue</item>
</style>

Toolbar styling

You can easily tweak the main toolbar style using the pspdf__mainToolbarStyle attribute of your theme:

<style name="MyApp.Theme" parent="Theme.MaterialComponents.Light.NoActionBar">
    <item name="pspdf__mainToolbarStyle">@style/MyApp.MainToolbarStyle</item>
</style>

<style name="MyApp.MainToolbarStyle">
    <item name="pspdf__backgroundColor">?colorPrimary</item>
    <item name="pspdf__textColor">@color/dark_icons_blue</item>

    <item name="pspdf__toolbarTheme">@style/ThemeOverlay.AppCompat.Dark.ActionBar</item>
    <item name="pspdf__toolbarPopupTheme">@style/ThemeOverlay.AppCompat.Light</item>
</style>

The following attributes can be modified for pspdf__mainToolbarStyle.

If you want to tweak the default appearance of the icons inside the PdfActivity’s action bar, you can apply an icon style using the pspdf__actionBarIconsStyle attribute of your theme:

<style name="MyApp.Theme" parent="Theme.MaterialComponents.Light.NoActionBar">
    <item name="pspdf__actionBarIconsStyle">@style/MyApp.ActionBarIconsStyle</item>
</style>

<style name="MyApp.ActionBarIconsStyle">
    <item name="pspdf__iconsColor">@color/dark_icons_blue</item>
    <item name="pspdf__iconsColorActivated">@color/color_dark</item>
</style>

The following attributes can be modified for pspdf__actionBarIconsStyle.

Styling contextual toolbars

Nutrient uses custom contextual toolbars to present annotation editing, annotation creation, text selection, and document editing toolbars. To style contextual toolbars, use the pspdf__contextualToolbarStyle attribute of your theme:

<style name="MyApp.Theme" parent="Theme.MaterialComponents.Light.NoActionBar">
    <item name="pspdf__contextualToolbarStyle">@style/MyApp.ContextualToolbarStyle</item>
</style>

<style name="MyApp.ContextualToolbarStyle">
    <item name="pspdf__backgroundColor">?colorPrimaryDark</item>
    <item name="pspdf__submenuBackgroundColor">?colorPrimary</item>
    <item name="pspdf__iconsColor">@color/pspdf__color_white</item>
    <item name="pspdf__iconsColorActivated">@color/pspdf__color_white</item>
</style>

The following attributes can be modified for pspdf__contextualToolbarStyle. Note that some of them only have an effect when the toolbar is not docked at the top of the screen, but rather dragged to float vertically on the left or right side of the page.

Additionally, you can customize each of the toolbars with their own configuration, as shown below.

Annotation creation toolbar

<item name="pspdf__annotationCreationToolbarIconsStyle">@style/MyApp.Theme.AnnotationCreationToolbarIconsStyle</item>

Annotation editing toolbar

<parameter name="pspdf__annotationEditingToolbarIconsStyle">@style/MyApp.Theme.AnnotationEditingToolbarIconsStyle</item>

Text selection toolbar

<item name="pspdf__textSelectionToolbarIconsStyle">@style/MyApp.Theme.TextSelectionToolbarIconsStyle</item>

Document editing toolbar

<item name="pspdf__documentEditingToolbarIconsStyle">@style/MyApp.Theme.DocumentEditingToolbarIconsStyle</item>

Toolbar coordinator layout

The positioning and moving of contextual toolbars is handled by the ToolbarCoordinatorLayout, which can also be themed:

<item name="pspdf__toolbarCoordinatorLayoutStyle">@style/MyApp.Theme.ToolbarCoordinatorLayoutStyle</item>

Inline search

<item name="pspdf__inlineSearchStyle">@style/MyApp.InlineSearchStyle</item>

Modular search

<item name="pspdf__modularSearchStyle">@style/MyApp.ModularSearchStyle</item>

Thumbnail bar

<item name="pspdf__thumbnailBarStyle">@style/MyApp.ThumbnailBarStyle</item>

Scrollable thumbnail bar

<item name="pspdf__scrollableThumbnailBarStyle">@style/MyApp.ScrollableThumbnailBarStyle</item>

Thumbnail grid

<item name="pspdf__thumbnailGridStyle">@style/MyApp.ThumbnailGridStyle</item>

Outline view

<item name="pspdf__outlineViewStyle">@style/MyApp.OutlineStyle</item>

Document

<item name="pspdf__documentViewStyle">@style/MyApp.DocumentViewStyle</item>

Annotations

Use this to style the appearance of PDF annotations:

<item name="pspdf__annotationStyle">@style/MyApp.AnnotationStyle</item>

Annotation hints

Use this to style the appearance of PDF annotation hints:

<item name="pspdf__annotationNoteHinterStyle">@style/MyApp.AnnotationHintsStyle</item>

Search result highlighter

This defines styling for the search result highlighter:

<item name="pspdf__searchResultHighlighterStyle">@style/MyApp.SearchResultHighlighterStyle</item>

Link annotation highlighter

This defines styling for the link annotations highlighter:

<item name="pspdf__linkAnnotationHighlighterStyle">@style/MyApp.LinkAnnotationHighlighterStyle</item>

Text selection

<item name="pspdf__textSelectionStyle">@style/MyApp.TextSelectionStyle</item>

Password view

<item name="pspdf__passwordViewStyle">@style/MyApp.PasswordViewStyle</item>

Signature layout

<item name="pspdf__passwordViewStyle">@style/MyApp.SignatureLayoutStyle</item>

Property inspector

<item name="pspdf__propertyInspectorStyle">@style/MyApp.PropertyInspectorStyle</item>

The modal dialog style is set inside the previously mentioned pspdf__propertyInspectorStyle via:

<item name="pspdf__modalDialogStyle">@style/MyApp.ModalDialog.PropertyInspector</item>

Action menu

This is used for styling the bottom action menu (pops up when sharing a document, for example):

<item name="pspdf__actionMenuStyle">@style/MyApp.ActionMenuStyle</item>

Stamp picker

<item name="pspdf__stampPickerStyle">@style/MyApp.StampPickerStyle</item>

Sharing dialog

<item name="pspdf__sharingDialogStyle">@style/MyApp.SharingDialogStyle</item>

New page dialog

<item name="pspdf__newPageDialogStyle">@style/MyApp.NewPageDialogStyle</item>

Settings dialog

This is used for styling the settings dialog that displays page layout and scroll direction options:

<item name="pspdf__settingsDialogStyle">@style/MyApp.SettingsDialogStyle</item>

Settings mode picker items

This is used for styling settings mode picker items:

<item name="pspdf__settingsModePickerItemStyle">@style/MyApp.SettingsModePickerItemStyle</item>

AI Assistant dialog

This is used for styling the AI Assistant chat dialog:

<item name="pspdf__aiAssistantDialogStyle">@style/MyApp.AIAssistantDialogStyle</item>

Document view

This accepts a style defining View attributes for modifying the appearance of scrollbars:

<item name="pspdf__documentViewStyle">@style/MyApp.DocumentViewStyle</item>

Form selection

<item name="pspdf__formSelectionStyle">@style/MyApp.FormSelectionStyle</item>

Form editing bar

<item name="pspdf__formEditingBarStyle">@style/MyApp.FormEditingBarStyle</item>

Popup toolbar

This is used for styling popup toolbars (e.g. when text is selected or when pasting elements):

<item name="pspdf__popupToolbarStyle">@style/MyApp.PopupToolbarStyle</item>

Content editing

This is used for styling content editing features:

<item name="pspdf__contentEditingStyle">@style/MyApp.ContentEditingStyle</item>

Content editing toolbar

This is used for styling the content editing toolbar:

<item name="pspdf__contentEditingToolbarStyle">@style/MyApp.ContentEditingToolbarStyle</item>

Content editing styling bar

This is used for styling the content editing styling bar that appears when editing text:

<item name="pspdf__contentEditingStylingBarStyle">@style/MyApp.ContentEditingStylingBarStyle</item>

Sound annotation icon

This is used for styling sound annotation icons:

<item name="pspdf__soundAnnotationIconStyle">@style/MyApp.SoundAnnotationIconStyle</item>

Audio inspector

This is used for styling the audio inspector bar:

<item name="pspdf__audioInspectorStyle">@style/MyApp.AudioInspectorStyle</item>

Note editor view

This is used for styling the note editor view:

<item name="pspdf__noteEditorStyle">@style/MyApp.NoteEditorStyle</item>

Eraser tool

This is used for styling the annotation eraser tool:

<item name="pspdf__eraserStyle">@style/MyApp.EraserStyle</item>

Stepper view

This is used for styling stepper views (multistep progress indicators) in the document comparison UI:

<item name="pspdf__stepperViewStyle">@style/MyApp.StepperViewStyle</item>

Breadcrumbs view

This is used for styling breadcrumb view (showing “old” > “new”) in the document comparison UI:

<item name="pspdf__breadCrumbsViewStyle">@style/MyApp.BreadCrumbsViewStyle</item>

Helper line

This is used for styling helper lines (snapping guides):

<item name="pspdf__helperLineStyle">@style/MyApp.HelperLineStyle</item>

Tab bar

This is used for styling the tab bar that’s shown when multiple documents are opened:

<item name="pspdf__tabBarStyle">@style/MyApp.TabBarStyle</item>

Annotation selection layout

Use this to style the appearance of the annotation selection layout:

<item name="pspdf__annotationSelectionStyle">@style/MyApp.AnnotationSelection</item>

When a scale handle drawable is set to null and the pspdf__scaleHandleColor is set to Color.TRANSPARENT, the scale handle will not be operational. When a drawable is set for a scale handle together with a color other than transparent, the drawable will take precedence over the color. When a background drawable is set by pspdf__backgroundDrawable together with pspdf__borderColor, the drawable will take precedence over the color.

Measurement tools

Use the following to style the appearance of the Measurement Tools attributes:

<item name="pspdf__measurementToolsStyle">@style/MyApp.MeasurementTools</item>

Customizing the Android status bar text color

By default, Android automatically chooses the status bar text color (white or black) based on the status bar’s background color. This means it isn’t possible to set a specific foreground color. Instead, you can let the OS know whether it should use a light or dark appearance, and it’ll choose the foreground color based on that.

Setting the status bar text color

You can control whether the status bar text and icons appear light or dark, depending on your app’s design.

For Android 11+ (API 30+)

import androidx.core.view.WindowInsetsControllerCompat

WindowInsetsControllerCompat(window, window.decorView).let { controller ->
    controller.isAppearanceLightStatusBars = true // Dark icons (light status bar)
}

For Android 8.0–10 (API 26–29)

window.decorView.systemUiVisibility = View.SYSTEM_UI_FLAG_LIGHT_STATUS_BAR

Changing the background color

You can also customize the status bar’s background to match your app’s theme or branding:

window.statusBarColor = Color.RED