@flitzinteractive/react-native-nitro-html-pdf

Generate professional PDF documents directly on device from HTML - perfect for invoices, receipts, reports, and contracts with custom headers, footers, and page numbers. No backend required, works offline, zero cloud costs.

---

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