@capgo/capacitor-printer

Print documents, HTML, PDFs, images and the current web view from your Capacitor app with the native print dialogs on iOS and Android.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-printer in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-printer to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• HTML: printHtml() prints an HTML string.
• PDF and files: printPdf(), printFile() and printBase64() for device files and base64 data.
• Web content: printWebView() prints the current page and printIframe() prints an iframe.
• Native dialogs: UIPrintInteractionController on iOS and the Android print framework.
• Platforms: iOS, Android and Web. Web uses the browser print dialog.

Why Capacitor Printer?

A free and open-source printing solution with comprehensive features:

• Multiple formats - Print HTML, PDFs, images, and base64 data
• Native APIs - Uses UIPrintInteractionController (iOS) and PrintManager (Android)
• Web support - Works across all platforms including web browsers
• Print customization - Support for CSS print styles and custom page names
• Cross-platform - Consistent API across iOS, Android, and Web

Perfect for invoice generation, report printing, document sharing, and any app requiring native printing capabilities.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/printer/

Compatibility

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-printer` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-printer
npx cap sync

Usage

import { Printer } from '@capgo/capacitor-printer';

// Print HTML content
await Printer.printHtml({
  name: 'My Document',
  html: '<html><body><h1>Hello World</h1><p>This is a test document.</p></body></html>',
});

// Print PDF file
await Printer.printPdf({
  name: 'Invoice',
  path: 'file:///path/to/document.pdf',
});

// Print image from base64
await Printer.printBase64({
  name: 'Photo',
  data: 'JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL...',
  mimeType: 'image/jpeg',
});

// Print current web view
await Printer.printWebView({
  name: 'Web Page',
});

API

• printBase64(...)
• printFile(...)
• printHtml(...)
• printPdf(...)
• printIframe(...)
• printWebView(...)
• getPluginVersion()
• Interfaces

printBase64(...)

printBase64(options: PrintBase64Options) => Promise<void>

Presents the printing UI to print files encoded as base64 strings.

Platform Behavior:

• iOS: Uses UIPrintInteractionController with base64 decoded data
• Android: Uses PrintManager with base64 decoded data
• Web: Creates a blob from base64 data and opens print dialog

Performance Warning: Large files can lead to app crashes due to memory constraints when decoding base64. For files larger than 5MB, it's recommended to use printFile() instead.

Since: 7.0.0

printFile(...)

printFile(options: PrintFileOptions) => Promise<void>

Presents the printing UI to print device files.

Platform Behavior:

• iOS: Uses UIPrintInteractionController with file URL. Supports file:// paths or paths relative to app's documents directory.
• Android: Uses PrintManager with file path. Supports both content:// URIs and file:// paths.
• Web: Reads file and opens print dialog

Supported File Types:

• PDF documents (application/pdf)
• Images: JPEG, PNG, GIF, HEIC, HEIF

Since: 7.0.0

printHtml(...)

printHtml(options: PrintHtmlOptions) => Promise<void>

Presents the printing UI to print HTML documents.

Platform Behavior:

• iOS: Renders HTML in WKWebView, then prints using UIPrintInteractionController
• Android: Renders HTML in WebView, then prints using PrintManager
• Web: Creates iframe with HTML content and triggers print dialog

HTML Requirements:

• Should be a complete HTML document with proper structure
• Can include inline CSS styles or style tags
• External resources (images, stylesheets) should use absolute URLs
• Print-specific CSS can be added using @media print rules

CSS Print Styling: Use CSS media queries to customize print output:

• Control page breaks: page-break-before, page-break-after, page-break-inside
• Hide elements: display: none for no-print classes
• Adjust font sizes and colors for print

Since: 7.0.0

printPdf(...)

printPdf(options: PrintPdfOptions) => Promise<void>

Presents the printing UI to print PDF documents.

Platform Behavior:

• iOS: Uses UIPrintInteractionController with PDF file URL
• Android: Uses PrintManager with PdfDocument
• Web: Creates object URL and opens print dialog

File Path Requirements:

• iOS: Must be file:// path or relative to app's documents directory
• Android: Supports content:// URIs (from downloads, media store) or file:// paths
• Web: Must be accessible file path

Since: 7.0.0

printIframe(...)

printIframe(options: PrintIframeOptions) => Promise<void>

Presents the printing UI for content inside an iframe element.

Useful when the full HTML document is too large to pass to printHtml().

Platform Behavior:

• iOS: Evaluates JavaScript in the WebView to print the iframe content
• Android: Evaluates JavaScript in the WebView to print the iframe content
• Web: Finds the iframe and triggers its print dialog

Since: 8.0.19

printWebView(...)

printWebView(options?: PrintOptions | undefined) => Promise<void>

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version.

Returns the hardcoded plugin version from native code (iOS/Android) or package version (Web). This is useful for debugging and ensuring plugin compatibility.

Returns: Promise<{ version: string; }>

Since: 7.0.0

Interfaces

PrintBase64Options

Options for printing base64 encoded data.

PrintFileOptions

Options for printing files from device storage.

PrintHtmlOptions

Options for printing HTML content.

PrintPdfOptions

Options for printing PDF documents.

PrintIframeOptions

Options for printing iframe content.

PrintOptions

Base options for all print operations.

Android Configuration

ProGuard

If you are using ProGuard, add the following rules to your proguard-rules.pro file:

-keep class com.capgo.printer.** { *; }

Variables

You can configure the following project variables in your variables.gradle file:

ext {
  androidxDocumentFileVersion = '1.0.1'
  androidxPrintVersion = '1.0.0'
}

Platform Support

Notes

Large Files

When printing base64 encoded data, large files can lead to app crashes due to memory constraints. For large files, it's recommended to save them to the device first and use printFile() instead.

Web Platform

On the web platform:

• printWebView() triggers the browser's native print dialog
• Other methods create an iframe and print its content
• Some browsers may have security restrictions on printing certain file types

Print Styles

When printing web content, you can use CSS media queries to customize the print output:

@media print {
  /* Your print styles here */
  body {
    font-size: 12pt;
  }
  .no-print {
    display: none;
  }
}