cap-printer-plugin

Capacitor plugin for thermal printers (ESC/POS) supporting USB, Bluetooth, and Network connections.

Install

npm install cap-printer-plugin
npx cap sync

API

• printText(...)
• printFormattedText(...)
• printBase64Image(...)
• printBarcode(...)
• printQRCode(...)
• feedLine(...)
• cutPaper(...)
• openCashBox(...)
• printBatch(...)
• getUsbDevices()
• getBluetoothDevices()
• getPrinters()
• Interfaces
• Type Aliases

printText(...)

printText(options: PrintTextOptions) => Promise<void>

Print plain text

| Param | Type | Description | | ------------- | ------------------------------------------------------------- | ------------------ | | options | PrintTextOptions | Print text options |

printFormattedText(...)

printFormattedText(options: PrintFormattedTextOptions) => Promise<void>

Print formatted text with alignment, attributes, and size

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------------- | ---------------------------- | | options | PrintFormattedTextOptions | Print formatted text options |

printBase64Image(...)

printBase64Image(options: PrintImageOptions) => Promise<void>

Print a base64 encoded image

| Param | Type | Description | | ------------- | --------------------------------------------------------------- | ------------------- | | options | PrintImageOptions | Print image options |

printBarcode(...)

printBarcode(options: PrintBarcodeOptions) => Promise<void>

Print a barcode

| Param | Type | Description | | ------------- | ------------------------------------------------------------------- | --------------------- | | options | PrintBarcodeOptions | Print barcode options |

printQRCode(...)

printQRCode(options: PrintQRCodeOptions) => Promise<void>

Print a QR code

| Param | Type | Description | | ------------- | ----------------------------------------------------------------- | --------------------- | | options | PrintQRCodeOptions | Print QR code options |

feedLine(...)

feedLine(options: FeedLineOptions) => Promise<void>

Feed paper by specified number of lines

| Param | Type | Description | | ------------- | ----------------------------------------------------------- | ----------------- | | options | FeedLineOptions | Feed line options |

cutPaper(...)

cutPaper(options: CutPaperOptions) => Promise<void>

Cut paper (partial cut)

| Param | Type | Description | | ------------- | ----------------------------------------------------------- | ----------------- | | options | CutPaperOptions | Cut paper options |

openCashBox(...)

openCashBox(options: OpenCashBoxOptions) => Promise<void>

Open the cash drawer

| Param | Type | Description | | ------------- | ----------------------------------------------------------------- | --------------------- | | options | OpenCashBoxOptions | Open cash box options |

printBatch(...)

printBatch(options: PrintBatchOptions) => Promise<void>

Execute multiple print operations in sequence

| Param | Type | Description | | ------------- | --------------------------------------------------------------- | ------------------- | | options | PrintBatchOptions | Batch print options |

getUsbDevices()

getUsbDevices() => Promise<GetDevicesResult>

Get list of available USB printers

Returns: Promise<GetDevicesResult>

getBluetoothDevices()

getBluetoothDevices() => Promise<GetDevicesResult>

Get list of paired Bluetooth printers Note: On Android 12+, this will automatically request Bluetooth permissions if needed

Returns: Promise<GetDevicesResult>

getPrinters()

getPrinters() => Promise<GetDevicesResult>

Get all available printers (USB and Bluetooth) Note: On Android 12+, this will automatically request Bluetooth permissions if needed

Returns: Promise<GetDevicesResult>

Interfaces

PrintTextOptions

| Prop | Type | | ------------- | --------------------------------------------------- | | printer | PrinterInfo | | text | string |

PrinterInfo

| Prop | Type | Description | | ---------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | type | ConnectionType | Connection type: 'usb', 'bluetooth', or 'network' | | id | string | Device identifier: - USB: VID:PID format (e.g., '0416:5011') or device path - Bluetooth: MAC address (e.g., '12:34:56:78:9A:BC') - Network: IP address (e.g., '192.168.1.100') |

PrintFormattedTextOptions

| Prop | Type | | --------------- | ------------------------------------------------------- | | printer | PrinterInfo | | text | string | | alignment | TextAlignment | | attribute | TextAttribute | | textSize | TextSize |

PrintImageOptions

| Prop | Type | Description | | ----------------- | ------------------------------------------------------- | ------------------------------------ | | printer | PrinterInfo | | | base64Image | string | Base64 encoded image data | | alignment | TextAlignment | | | width | number | Image width in pixels (default: 384) |

PrintBarcodeOptions

| Prop | Type | Description | | ----------------- | ------------------------------------------------------- | -------------------------------------------- | | printer | PrinterInfo | | | data | string | | | barcodeType | BarcodeType | | | alignment | TextAlignment | | | width | number | Barcode width (2-6, default: 3) | | height | number | Barcode height in dots (1-255, default: 162) |

PrintQRCodeOptions

| Prop | Type | Description | | --------------- | ------------------------------------------------------- | -------------------------------------- | | printer | PrinterInfo | | | data | string | | | size | number | QR code module size (1-16, default: 8) | | alignment | TextAlignment | |

FeedLineOptions

| Prop | Type | | ------------- | --------------------------------------------------- | | printer | PrinterInfo | | lines | number |

CutPaperOptions

| Prop | Type | | ------------- | --------------------------------------------------- | | printer | PrinterInfo |

OpenCashBoxOptions

| Prop | Type | | ------------- | --------------------------------------------------- | | printer | PrinterInfo |

PrintBatchOptions

| Prop | Type | | ------------- | --------------------------------------------------- | | printer | PrinterInfo | | items | PrintItemType[] |

GetDevicesResult

| Prop | Type | | ------------- | ------------------------- | | devices | DeviceInfo[] |

DeviceInfo

| Prop | Type | Description | | ---------- | --------------------------------------------------------- | --------------------------------------------- | | id | string | Device identifier (varies by connection type) | | name | string | Device display name | | type | ConnectionType | Connection type |

Type Aliases

ConnectionType

'usb' | 'bluetooth' | 'network'

TextAlignment

'left' | 'center' | 'right'

TextAttribute

'normal' | 'bold' | 'underline' | 'bold_underline'

TextSize

'normal' | 'wide' | 'tall' | 'large'

BarcodeType

'UPC_A' | 'UPC_E' | 'EAN8' | 'EAN13' | 'CODE39' | 'CODE93' | 'CODE128'

PrintItemType

{ type: 'text'; text: string } | { type: 'formattedText'; text: string; alignment?: TextAlignment; attribute?: TextAttribute; textSize?: TextSize } | { type: 'image'; base64Image: string; alignment?: TextAlignment; width?: number } | { type: 'barcode'; data: string; barcodeType?: BarcodeType; alignment?: TextAlignment; width?: number; height?: number } | { type: 'qrcode'; data: string; size?: number; alignment?: TextAlignment } | { type: 'feedLine'; lines: number } | { type: 'cutPaper' }

Usage Examples

Print Text to Network Printer

import { CapacitorPrinter } from 'cap-printer-plugin';

await CapacitorPrinter.printText({
  printer: { type: 'network', id: '192.168.1.100' },
  text: 'Hello, World!\n'
});

Print Formatted Receipt

await CapacitorPrinter.printFormattedText({
  printer: { type: 'network', id: '192.168.1.100' },
  text: 'RECEIPT',
  alignment: 'center',
  attribute: 'bold',
  textSize: 'large'
});

Print QR Code

await CapacitorPrinter.printQRCode({
  printer: { type: 'usb', id: '0416:5011' },
  data: 'https://example.com',
  size: 8
});

Batch Printing

await CapacitorPrinter.printBatch({
  printer: { type: 'bluetooth', id: '12:34:56:78:9A:BC' },
  items: [
    { type: 'formattedText', text: 'STORE NAME', alignment: 'center', attribute: 'bold' },
    { type: 'feedLine', lines: 1 },
    { type: 'text', text: 'Item 1         $10.00\n' },
    { type: 'text', text: 'Item 2         $15.00\n' },
    { type: 'feedLine', lines: 1 },
    { type: 'qrcode', data: 'RECEIPT-12345' },
    { type: 'cutPaper' }
  ]
});

Discover Printers

const result = await CapacitorPrinter.getPrinters();
console.log('Available printers:', result.devices);

Android Setup

Add the following permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

iOS Setup

Add the following to your Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to connect to printers</string>
<key>NSLocalNetworkUsageDescription</key>
<string>This app uses local network to connect to network printers</string>
<key>UISupportedExternalAccessoryProtocols</key>
<array>
    <string>com.yourprotocol.printer</string>
</array>

License

MIT