Customizing PDF viewer styling on Android

To customize UI elements, Nutrient Android SDK 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 Android SDK (toolbars, views, dialogs, etc.) use these colors to style the rest of the UI.

Out of the box, Nutrient Android SDK 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.

Adding insets around document content

Use PdfFragment#setInsets() to add padding around the fragment’s document content. This is useful when your app renders its own toolbar, bottom sheet, or overlay next to the viewer. The PDF pages then need to avoid that area.

Insets apply in pixels to the left, top, right, and bottom edges of the fragment content. They don’t change the PDF page size or the document’s stored page boxes.

Defining a custom theme

Since Nutrient Android SDK adheres to Android’s style and theme framework, you have full control over styling the appearance of all Nutrient Android SDK components. The PdfActivity is built on top of AndroidX AppCompat and Material Components, so your theme has to inherit from a Theme.MaterialComponents theme. The SDK’s own themes inherit from Theme.MaterialComponents.Light.NoActionBar.Bridge (PSPDFKit.Theme.Default) and Theme.MaterialComponents.NoActionBar.Bridge (PSPDFKit.Theme.Dark).

PdfActivity uses a custom toolbar system, so you must deactivate the decor action bar of the activity. The easiest way is to use the default Nutrient Android SDK 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 Android SDK comes with several styleable components. -->
       <item name="pspdf__mainToolbarStyle">@style/MyMainToolbar</item>
   </style>
   
   <style name="MyMainToolbar">
       <item name="pspdf__textColor">@color/my_toolbar_text_color</item>
   </style>

   If you want to use a different parent theme, you can manually disable the default window decor action bar. Set 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>

You can set a custom theme in the manifest or via PdfActivityConfiguration#Builder. In default mode, set it via PdfActivityConfiguration.Builder#theme(int), and in night theme mode, set it via PdfActivityConfiguration.Builder#themeDark(int). A custom theme set through the builder configuration overwrites the custom theme set in the manifest.

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

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

This means that Nutrient Android SDK uses default values for all styles the current theme’s customization doesn’t cover.

Theming from code with a color scheme

As an alternative to XML theme attributes, you can theme the SDK’s screens from code. Call setColorScheme() on PdfActivity or PdfUiFragment with a Compose UiColorScheme. Each screen takes its colors from its part of the scheme:

The XML theme stays the default, and setColorScheme(null) returns to it. To build a scheme from your Material 3 colors or your XML theme, see theming from code. That guide also covers setting one accent color, following light and dark mode, and matching your Compose content.

Available styles

Nutrient Android SDK provides a large set of style attributes for default and dark themes. This enables you to alter the appearance according to your needs.

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

The main toolbar is rendered in Jetpack Compose and reads its colors from 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.

You can set the same colors from code as the mainToolbar part of a UiColorScheme. On PdfActivity and PdfUiFragment, pass the scheme to setColorScheme(), which overrides the XML values until you call it with null. See what each part colors for an example. On a host-rendered NutrientMainToolbar, use its colors parameter or a surrounding NutrientTheme. setMainToolbarColorScheme() is deprecated. It still colors only the main toolbar and takes precedence over setColorScheme() there, so stop calling it when you switch.

MainToolbarColors also carries iconColor, iconSelectedColor, and iconDisabledColor. They color the built-in toolbar items, the overflow button, and items you add without a tint of their own. A scheme from UiColorScheme.fromXmlTheme() takes them from the pspdf__actionBarIconsStyle below. In a scheme you build yourself, unset icon colors follow textColor. MainToolbarColors also carries documentTitleOverlay for the title strip the toolbar draws below itself. The shape of an item’s pressed and selected state is a ToolbarItemIndication, passed to the composables.

To tweak the icons of the PdfActivity’s main toolbar, 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.

A custom item added with a ToolbarItemsProvider carries its own ToolbarIcon and is tinted with pspdf__iconsColor automatically.

Styling contextual toolbars

Nutrient Android SDK 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. The annotation creation, document editing, and content editing toolbars all read this one style. The border colors only have an effect when the toolbar is docked at a side of the screen.

No per-toolbar or per-item icon attributes exist. To replace an item’s icon, return a copy with a different ToolbarIcon from ToolbarCoordinator.updateContextualItems, as shown in customizing contextual toolbars. A color scheme set with setColorScheme() colors these toolbars through its contextualToolbar part, a ContextualToolbarColors. A host that renders the bar itself with NutrientContextualToolbar passes a MainToolbarColors instead.

Note editor toolbar

Set this attribute to style the note editor toolbar:

<item name="pspdf__noteEditorToolbarIconsStyle">@style/MyApp.Theme.NoteEditorToolbarIconsStyle</item>

The text selection toolbar is a popup and is styled with pspdf__popupToolbarStyle; see popup toolbar.

Toolbar docking

The dock slots and drop-zone chrome the contextual toolbars use when dragged, along with the toolbar’s height, are themed through pspdf__toolbarCoordinatorLayoutStyle:

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

Inline search

The inline search bar is part of the main toolbar and takes its colors from pspdf__mainToolbarStyle; it has no style of its own.

Modular search

Use this attribute to style the modular search view:

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

Thumbnail bar

Use this attribute to style the thumbnail bar:

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

A color scheme set with setColorScheme() colors both thumbnail bars through its thumbnailBar part, a ThumbnailBarColors. PdfThumbnailBar.setBackgroundColor(), setThumbnailBorderColor(), and setSelectedThumbnailBorderColor() take precedence over both the scheme and these attributes.

Scrollable thumbnail bar

Use this attribute to style the scrollable thumbnail bar:

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

Thumbnail grid

The document overview grid is rendered in Jetpack Compose and keeps these attributes. It has no floating action button (FAB) since 12.0; document editing is entered from the main toolbar’s document editor item, themed with pspdf__documentEditorIcon.

Use this attribute to style the thumbnail grid:

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

A color scheme set with setColorScheme() colors the grid through its thumbnailGrid part, a ThumbnailGridColors.

Outline view

Use this attribute to style the outline view:

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

pspdf__maxWidth defaults to @dimen/pspdf__sheet_max_width (480dp) and sets the side sheet’s exact width and the bottom sheet’s maximum. pspdf__sheetPresentationMode decides whether the outline presents as a bottom sheet or an end-anchored side sheet on large windows, defaulting to auto. Note that pspdf__width silently wins when your theme sets it to a positive value. Check it first if pspdf__maxWidth appears to have no effect. See modal dialogs for details.

A color scheme set with setColorScheme() colors the outline view and its lists through its outline part, an OutlineColors, and document info through documentInfoColorScheme.

Document

Use this attribute to style the document view:

<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

Use this attribute to style text selection:

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

When the theme doesn’t set pspdf__leftHandleColor and pspdf__rightHandleColor, the handle colors are derived from pspdf__highlightColor: darker on a light page and lighter on an inverted page. To keep a fixed handle color, set both handle attributes.

Password view

Use this attribute to style the password view:

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

Signature layout

Use this attribute to style the signature layout:

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

Property inspector

Use this attribute to style the 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>

A color scheme set with setColorScheme() colors the action menu through its actionMenu part, an ActionMenuColors. Its fixedActionsIconColor tints the fixed action icons.

Stamp picker

Use this attribute to style the stamp picker:

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

Sharing dialog

Use this attribute to style the sharing dialog:

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

New page dialog

Use this attribute to style the 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>

A color scheme set with setColorScheme() colors the settings sheet through its settingsColorScheme part, a SettingsColorScheme.

Settings mode picker items

This is used for styling settings mode picker items:

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

Under a color scheme set with setColorScheme(), the item icons take unselectedIconColor and disabledIconColor from its settingsColorScheme instead. A scheme from UiColorScheme.fromXmlTheme() fills both from this tint.

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

Use this attribute to style form selection:

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

Form editing bar

Use this attribute to style the 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

The content editing toolbar is a contextual toolbar and is styled with pspdf__contextualToolbarStyle; see styling contextual toolbars.

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 the 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>

The tab bar is rendered in Jetpack Compose, and these attributes are read into a TabBarColors and NutrientTabBarDimensions. A color scheme set with setColorScheme() replaces the colors with its tabBar part. A host that composes NutrientTabBar itself passes those directly, or builds them from a Material theme with getTabBarColors(). pspdf__tabIconColor applies to the close button of unselected tabs, which only show one in PdfTabBarCloseMode.CLOSE_ENABLED.

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 null and pspdf__scaleHandleColor is Color.TRANSPARENT, the scale handle isn’t operational. If you set both a drawable and a color other than transparent, the drawable takes precedence over the color. The same applies to pspdf__backgroundDrawable and pspdf__borderColor.

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 tell the operating system (OS) whether to use a light or dark appearance, and it chooses the foreground color accordingly.

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+)

On Android 11 and later, use WindowInsetsControllerCompat to set the appearance:

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)

On Android 8.0 through 10, set the system UI visibility flag on the decor view:

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