Features

• ✅ Vector-based PDF generation (text remains selectable)
• ✅ Custom headers and footers with vector quality
• ✅ Automatic page numbering
• ✅ Multiple page sizes (A4, A3, A5, Letter, Legal)
• ✅ Custom margins
• ✅ iOS and Android support
• ✅ Built with Nitro Modules for optimal performance
• ✅ No Backend Required - Works offline
• ✅ Privacy-First - No data sent to servers
• ✅ Zero Cloud Costs - Local PDF generation

Use Cases

This library is perfect for:

• 📄 Invoices and Receipts - Professional documents with company headers and page numbers
• 📊 Reports - Multi-page reports with consistent branding
• 📋 Contracts - Legal documents with headers, footers, and pagination
• 🎓 Certificates - Custom-designed certificates with vector quality
• 💳 Statements - Bank statements, account summaries, etc.
• 🎫 Tickets and Passes - Event tickets, boarding passes, etc.
• 📑 Documentation - Technical manuals, user guides
• 💼 Business Documents - Proposals, quotes, presentations

Installation

npm install @flitzinteractive/react-native-nitro-html-pdf react-native-nitro-modules

Or with yarn:

yarn add @flitzinteractive/react-native-nitro-html-pdf react-native-nitro-modules

react-native-nitro-modules is required as this library relies on Nitro Modules.

Android Setup

Add to your MainActivity.kt:

import com.margelo.nitro.nitrohtmlpdf.NitroHtmlPdf

override fun onCreate(savedInstanceState: android.os.Bundle?) {
    super.onCreate(savedInstanceState)
    NitroHtmlPdf.appContext = applicationContext
}

Usage

Basic Example

import { generatePdf } from '@flitzinteractive/react-native-nitro-html-pdf';

const result = await generatePdf({
  html: '<h1>Hello World</h1><p>This is a PDF document.</p>',
  fileName: 'document.pdf',
  pageSize: 'A4',
});

console.log('PDF created at:', result.filePath);

With Header and Footer

const result = await generatePdf({
  html: '<h1>Invoice</h1><p>Invoice content...</p>',
  fileName: 'invoice.pdf',
  pageSize: 'A4',
  header: '<div style="text-align: center;"><h3>Company Name</h3></div>',
  footer: '<div style="text-align: center;"><p>Thank you!</p></div>',
  headerHeight: 100,  // Required when using header
  footerHeight: 80,   // Required when using footer
  showPageNumbers: true,
  pageNumberFormat: 'Page {page} of {total}',
  marginTop: 20,
  marginBottom: 20,
});

API Reference

generatePdf(options: PdfOptions): Promise<PdfResult>

PdfOptions

| Property | Type | Required | Default | Description | |----------|------|----------|---------|-------------| | html | string | ✅ | - | HTML content to convert to PDF | | fileName | string | ✅ | - | Output PDF file name (must end with .pdf) | | pageSize | 'A4' \| 'A3' \| 'A5' \| 'LETTER' \| 'LEGAL' | ❌ | 'A4' | Page size | | header | string | ❌ | - | HTML content for header | | footer | string | ❌ | - | HTML content for footer | | headerHeight | number | ⚠️ | - | Header height in pixels (required if header is provided) | | footerHeight | number | ⚠️ | - | Footer height in pixels (required if footer is provided) | | showPageNumbers | boolean | ❌ | false | Show page numbers in footer | | pageNumberFormat | string | ❌ | 'Page {page} of {total}' | Page number format | | pageNumberFontSize | number | ❌ | 12 | Page number font size | | marginTop | number | ❌ | 0 | Top margin in pixels | | marginBottom | number | ❌ | 0 | Bottom margin in pixels | | marginLeft | number | ❌ | 0 | Left margin in pixels | | marginRight | number | ❌ | 0 | Right margin in pixels | | directory | string | ❌ | Cache dir | Output directory path |

PdfResult

interface PdfResult {
  filePath: string;  // Absolute path to generated PDF
  success: boolean;  // Whether generation succeeded
  error?: string;    // Error message if failed
}

Important Notes

Header and Footer Heights

You must provide explicit headerHeight and footerHeight values when using headers or footers. The library does not auto-calculate these values.

// ❌ Wrong - will throw error
await generatePdf({
  html: '...',
  fileName: 'doc.pdf',
  header: '<h3>Header</h3>',  // Missing headerHeight!
});

// ✅ Correct
await generatePdf({
  html: '...',
  fileName: 'doc.pdf',
  header: '<h3>Header</h3>',
  headerHeight: 100,  // Explicit height
});

Page Size Dimensions

• A4: 595 × 842 pts (210 × 297 mm)
• A3: 842 × 1191 pts (297 × 420 mm)
• A5: 420 × 595 pts (148 × 210 mm)
• Letter: 612 × 792 pts (8.5 × 11 in)
• Legal: 612 × 1008 pts (8.5 × 14 in)

Margin Behavior

The library automatically adjusts content margins to prevent overlap:

• Total top margin = marginTop + headerHeight
• Total bottom margin = marginBottom + footerHeight + (showPageNumbers ? 20 : 0)

Supported HTML/CSS

Both iOS and Android use native WebView rendering, supporting:

• Standard HTML5 tags
• CSS styling (inline, <style> tags)
• Tables, lists, images
• Custom fonts (with proper CSS @font-face)

Error Handling

try {
  const result = await generatePdf(options);
  
  if (result.success) {
    console.log('PDF created:', result.filePath);
  } else {
    console.error('PDF generation failed:', result.error);
  }
} catch (error) {
  console.error('Unexpected error:', error);
}

Common Errors

| Error | Cause | Solution | |-------|-------|----------| | headerHeight must be provided | Using header without height | Add headerHeight property | | footerHeight must be provided | Using footer without height | Add footerHeight property | | Combined header, footer, and margins exceed page height | Heights too large | Reduce header/footer/margin values | | File name must end with .pdf | Invalid file name | Ensure fileName ends with .pdf | | HTML content cannot be empty | Empty HTML | Provide valid HTML content |

Platform Differences

Android

• Uses PrintDocumentAdapter for vector rendering
• PDFs merged using PDFBox LayerUtility
• Text remains selectable in output PDF

iOS

• Uses UIPrintPageRenderer for vector rendering
• Native PDF context drawing
• Text remains selectable in output PDF

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Crafted with vision by Flitz Interactive