# PDF

Canonical page: https://docs.ovok.com/native-sdk/guide/components/pdf

The PDF module provides a comprehensive solution for displaying PDF documents within React Native applications. Built on top of [react-native-pdf](https://github.com/wonday/react-native-pdf) with enhanced loading states, theme integration, and automatic error handling for seamless document viewing experiences.

## Overview [#overview]

The PDF module offers a streamlined approach to PDF document rendering with built-in loading animations, consistent theming, and robust error handling. It supports both local and remote PDF files with smooth transitions and user-friendly loading states.

### Key Features [#key-features]

- **Seamless PDF Rendering**: Built on [react-native-pdf](https://github.com/wonday/react-native-pdf) for reliable cross-platform document display
- **Enhanced Loading States**: Animated loading indicators with fade in/out transitions using react-native-reanimated
- **Theme Integration**: Automatic theme-aware styling with backdrop colors and consistent design
- **Error Handling**: Built-in error management for network failures and invalid documents
- **Flexible Styling**: Customizable container and PDF styles for various layout requirements
- **Test Coverage**: Comprehensive unit tests for reliable component behavior

### Architecture [#architecture]

The PDF module follows the SDK's architectural principles:

- **Single Component**: Focused PDFViewer component for all PDF viewing needs
- **Props-based Customization**: Style, behavior, and content customization through props
- **Theme Integration**: Automatic integration with the app's theme system
- **Performance Optimized**: Efficient rendering with conditional loading states

### Basic Example [#basic-example]

```typescript
import { PDFViewer } from "@ovok/native/pdf";
import * as React from "react";

const TermsScreen = () => {
  const handleLoadComplete = (pages: number) => {
    console.log(`Terms document has ${pages} pages`);
  };

  return (
    <PDFViewer
      sourceURI="https://s2.q4cdn.com/175719177/files/doc_presentations/Placeholder-PDF.pdf"
      onLoadComplete={handleLoadComplete}
      containerStyle={{ margin: 16 }}
    />
  );
};

export default TermsScreen;

```

## Props [#props]

Every prop, with its type and description, is listed in the [`@ovok/native/pdf` API reference](/native-sdk/reference/pdf).

## Component Behavior [#component-behavior]

### Loading states [#loading-states]

1. **Initial Loading**: Shows animated loading indicator with theme-aware backdrop
2. **Document Ready**: Displays PDF content with fade-in animation
3. **Error callback**: Forwards loading failures through the inherited `onError`
   callback; the SDK does not render a separate error screen.

### Animation System [#animation-system]

- Uses `react-native-reanimated` for smooth fade in/out transitions
- Loading indicator appears immediately when `sourceURI` is provided
- Content fades in seamlessly when document is ready

### Theme Integration [#theme-integration]

- Automatically applies theme colors for loading backdrop
- Respects app theme for consistent visual experience
- Uses `useAppTheme` hook for dynamic theming

The viewer shows its loading overlay until `onLoadComplete` fires. A missing or
failing source is reported through the inherited PDF callback, but the component
does not replace that callback with an SDK-owned error UI. Render your own error
state around the viewer when the app needs a retry or empty state.