---
title: "Flutter PDF viewer styling — Flexible and customizable | Nutrient"
canonical_url: "https://www.nutrient.io/guides/flutter/user-interface/appearance-styling/"
md_url: "https://www.nutrient.io/guides/flutter/user-interface/appearance-styling.md"
last_updated: "2026-06-02T22:02:09.501Z"
description: "Customize the appearance of the Nutrient PDF viewer in Flutter. Style Android with XML theme resources and iOS with programmatic ThemeConfiguration."
---

# 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

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

```dart

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:

```dart

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](https://www.nutrient.io/guides/android/customizing-the-interface/appearance-styling.md) guide.

## iOS

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

```dart

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](https://www.nutrient.io/guides/ios/customizing-the-interface/appearance-styling.md) guide.

## Cross-platform theming

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

```dart

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

## Related pages

- [Localization: Change languages in our Flutter PDF viewer](/guides/flutter/user-interface/localization.md)
- [Customizing our PDF viewer in Flutter](/guides/flutter/user-interface.md)
- [Configuring PDF view properties](/guides/flutter/user-interface/configuration.md)
- [NutrientView Flutter widget](/guides/flutter/user-interface/nutrientview.md)
- [Show or hide the UI in our Flutter viewer](/guides/flutter/user-interface/ui-visibility.md)
- [View configuration reference](/guides/flutter/user-interface/view-configuration.md)