Customizing PDF viewer styling in Flutter

Nutrient Flutter SDK supports per-platform appearance customization:

  • Android — XML theme resources passed by name through PdfConfiguration
  • iOS — Programmatic colors via ThemeConfiguration in PdfConfiguration

Android

The Nutrient SDK on Android resolves colors from XML theme attributes at view inflation time. Define a theme in XML and reference it in PdfConfiguration.

1. Create the theme resource

Add android/app/src/main/res/values/nutrient_theme.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <color name="viewer_bg">#FF1E1E2E</color>
    <color name="viewer_toolbar_bg">#FF181825</color>
    <color name="viewer_status_bar">#FF11111B</color>
    <color name="viewer_icons">#FFCDD6F4</color>
    <color name="viewer_icons_active">#FF89B4FA</color>


    <!-- Inherit from the SDK default theme to preserve base styles. -->
    <style name="MyApp.NutrientTheme" parent="PSPDFKit.Theme.Default">
        <item name="colorPrimary">@color/viewer_toolbar_bg</item>
        <item name="colorPrimaryDark">@color/viewer_status_bar</item>
        <item name="colorAccent">@color/viewer_icons_active</item>
        <item name="windowActionBar">false</item>
        <item name="windowNoTitle">true</item>
        <item name="windowActionModeOverlay">true</item>
        <!-- Use the pspdf__ prefix for Nutrient-specific attributes. -->
        <item name="pspdf__backgroundColor">@color/viewer_bg</item>
        <item name="pspdf__actionBarIconsStyle">@style/MyApp.ActionBarIcons</item>
        <item name="pspdf__contextualToolbarStyle">@style/MyApp.ContextualToolbar</item>
    </style>


    <style name="MyApp.ActionBarIcons" parent="PSPDFKit.ActionBarIcons">
        <item name="pspdf__iconsColor">@color/viewer_icons</item>
        <item name="pspdf__iconsColorActivated">@color/viewer_icons_active</item>
    </style>


    <style name="MyApp.ContextualToolbar" parent="PSPDFKit.ContextualToolbar">
        <item name="pspdf__iconsColor">@color/viewer_icons</item>
        <item name="pspdf__iconsColorActivated">@color/viewer_icons_active</item>
    </style>
</resources>

2. Reference the theme from Flutter 

PdfConfiguration(
  // The name must match the style name in the XML resource exactly.
  androidDefaultThemeResource: 'MyApp.NutrientTheme',
)

3. Add dark appearance support

Provide separate themes for light and dark modes:

PdfConfiguration(
  androidDefaultThemeResource: 'MyApp.NutrientTheme.Light',
  // Applied automatically when the device is in dark mode.
  androidDarkThemeResource: 'MyApp.NutrientTheme.Dark',
)

To customize additional components (search, thumbnails, dialogs), add more pspdf__ attributes. For the full list, refer to the Nutrient Android appearance styling guide.

iOS

On iOS, colors are set programmatically via ThemeConfiguration. No native resource files are required:

PdfConfiguration(
  themeConfiguration: const ThemeConfiguration(
    // Main viewer background behind the PDF pages.
    backgroundColor: Color(0xFF1E1E2E),
    toolbar: ToolbarTheme(
      // Navigation bar at the top of the viewer.
      backgroundColor: Color(0xFF181825),
      iconColor: Color(0xFFCDD6F4),
      titleColor: Color(0xFFCDD6F4),
    ),
    annotationToolbar: AnnotationToolbarTheme(
      // Annotation toolbar shown when annotations are active.
      backgroundColor: Color(0xFF1E1E2E),
      iconColor: Color(0xFFBAC2DE),
      activeIconColor: Color(0xFF89B4FA),
    ),
  ),
)

Available properties

  • backgroundColor — Viewer background behind PDF pages
  • toolbar.backgroundColor — Navigation bar background
  • toolbar.iconColor — Toolbar button tint
  • toolbar.titleColor — Toolbar title text
  • annotationToolbar.backgroundColor — Annotation toolbar background
  • annotationToolbar.iconColor — Annotation toolbar icons
  • annotationToolbar.activeIconColor — Active annotation tool icon

For more information, refer to the Nutrient iOS appearance styling guide.

Cross-platform theming

To apply platform-specific theming in a single PdfConfiguration, use Platform checks:

import 'dart:io';


PdfConfiguration(
  // Android reads the theme from the XML resource at inflation time.
  androidDefaultThemeResource:
      Platform.isAndroid ? 'MyApp.NutrientTheme' : null,
  // iOS applies colors programmatically; ignored on Android.
  themeConfiguration: Platform.isIOS
      ? const ThemeConfiguration(
          backgroundColor: Color(0xFF1E1E2E),
          toolbar: ToolbarTheme(
            backgroundColor: Color(0xFF181825),
            iconColor: Color(0xFFCDD6F4),
          ),
          annotationToolbar: AnnotationToolbarTheme(
            backgroundColor: Color(0xFF1E1E2E),
            iconColor: Color(0xFFBAC2DE),
            activeIconColor: Color(0xFF89B4FA),
          ),
        )
      : null,
)

Troubleshooting

  • Android theme not applying — Verify the style name matches exactly. Run flutter clean && flutter build apk to pick up resource changes.
  • Android toolbar icons wrong color — Set pspdf__backgroundColor for the viewer and colorPrimary for the toolbar. Don’t set android:colorBackground.
  • iOS toolbar background not changing — Confirm backgroundColor is set in ToolbarTheme, not only at the top-level ThemeConfiguration.
  • System theme overriding colors — Set appearanceMode: AppearanceMode.defaultMode in PdfConfiguration to prevent the system appearance from overriding custom colors.