PDF Preview Guide

This guide covers how to display PDF documents inline using pdf-preview code blocks.

Overview

The pdf-preview block renders PDF files inline in chat messages — showing the first page with an expand button for full multi-page navigation in a fullscreen overlay.

Key principle: Unlike html-preview which needs transform_data to extract HTML, PDFs are already files on disk. Just reference the file path directly — no extraction step needed.

When to Use

Use pdf-preview when:

• Tool results reference a PDF file — Read tool, file downloads, API responses with PDF paths
• Generated reports — Scripts or tools that produce PDF output
• Downloaded documents — PDFs fetched from APIs or saved from web
• User asks to view a PDF — Any PDF file the user mentions or references

Do NOT use pdf-preview when:

• Content is structured data — use datatable or spreadsheet instead
• Content is HTML — use html-preview instead
• The PDF is a code/text file — just read it and present as markdown
• The user wants to extract text from the PDF — use the Read tool's PDF support instead

Basic Usage

Single Item

```pdf-preview
{
  "src": "/absolute/path/to/file.pdf",
  "title": "Q4 Financial Report"
}
```

Multiple Items (Tabs)

When you have multiple related PDFs (e.g., quarterly reports, contract versions), use the items array. A tab bar appears below the header for switching between items.

```pdf-preview
{
  "title": "Quarterly Reports",
  "items": [
    { "src": "/path/to/q1-report.pdf", "label": "Q1" },
    { "src": "/path/to/q2-report.pdf", "label": "Q2" },
    { "src": "/path/to/q3-report.pdf", "label": "Q3" }
  ]
}
```

Content loads lazily on tab switch and is cached once loaded.

Config Fields

*Either src (single) or items (multiple) is required. If both are present, items takes precedence.

Important: The src path must be an absolute path. Use the exact path from tool results or construct one using known directory paths.

Common Patterns

After Using the Read Tool on a PDF

When the Read tool reads a PDF, the file already exists on disk. Reference it directly:

```pdf-preview
{
  "src": "/Users/john/Documents/report.pdf",
  "title": "Annual Report 2025"
}
```

PDF from API Download

When a tool downloads a PDF (e.g., from an API response that returns binary data):

1. The file is typically saved to the session downloads folder
2. Reference the saved path in the pdf-preview block

```pdf-preview
{
  "src": "/absolute/path/to/downloaded/invoice.pdf",
  "title": "Invoice #12345"
}
```

PDF Generated by a Script

When running a Python script that generates a PDF (e.g., with reportlab, fpdf2, or weasyprint):

# Example: generate PDF with fpdf2
from fpdf import FPDF
import sys

pdf = FPDF()
pdf.add_page()
pdf.set_font('Helvetica', size=16)
pdf.cell(text='Hello World')
pdf.output(sys.argv[-1])

Call via transform_data, then reference the output:

```pdf-preview
{
  "src": "/absolute/path/from/transform_data/report.pdf",
  "title": "Generated Report"
}
```

PDF from User's Filesystem

When the user references a PDF they have locally:

```pdf-preview
{
  "src": "/Users/john/Downloads/contract.pdf",
  "title": "Service Agreement"
}
```

Rendering Behavior

Inline Preview

• Shows first page only at max-height 400px with bottom fade gradient
• White background — standard for PDF documents
• Expand button (top-right corner, visible on hover) opens fullscreen view
• Header bar shows FileText icon and title
• No pagination controls inline — use fullscreen for multi-page navigation

Fullscreen Overlay

• Full page-by-page navigation with prev/next buttons
• Page counter showing "Page X / Y"
• Copy path button copies the file path to clipboard
• "PDF" badge in header identifies the content type
• Text selection and annotation layers enabled for interactivity

Performance Notes

• PDFs are loaded as binary data (Uint8Array) via IPC — efficient even for large files
• The pdf.js worker handles decoding and rendering in a background thread
• Inline preview only renders page 1 — remaining pages load on-demand in fullscreen
• The file object is memoized to prevent unnecessary re-renders

Integration with Read Tool

The Read tool already supports reading PDFs with the pages parameter. Use pdf-preview for visual rendering and Read for text extraction:

Decision Tree

Does the user want to SEE the document?
  → YES: Use pdf-preview (visual fidelity matters)
  → NO: Extract text with Read tool and present as markdown

Is the content already a PDF file on disk?
  → YES: Use pdf-preview with direct file path
  → NO: Is it HTML? → Use html-preview
        Is it data? → Use datatable/spreadsheet
        Is it binary from an API? → Save to file first, then pdf-preview

Troubleshooting

"Loading..." shown indefinitely

• The "src" path must be an absolute path — not relative
• Verify the file exists at the specified path
• Check that the file is actually a PDF (not renamed HTML, etc.)

Blank/white preview

• The PDF file may be empty or corrupted
• Some encrypted PDFs require a password — pdf.js cannot render these
• Try opening the file with a system PDF viewer to verify it's valid

First page looks cut off

• The inline preview has a max-height of 400px — this is by design
• Click the expand button (top-right) for full-page rendering
• In fullscreen, the page renders at full size with scrolling

"Failed to render PDF" error

• The file may not be a valid PDF
• Very large PDFs (100MB+) may fail to load — consider extracting specific pages first
• Scanned PDFs render as images — this is expected behavior

Fullscreen overlay shows different content

• The overlay loads the PDF independently from the file path
• If the file was modified between inline load and fullscreen open, content may differ

Text not selectable in inline preview

• Text selection is intentionally disabled in the inline preview (renders without text layer for performance)
• Open fullscreen view for text selection support — the text layer is enabled there