Capacitor Cat Printer

A Capacitor plugin for thermal printers (Cat printers and compatibles) over Bluetooth LE. Works on Android and Web/PWA.

Features

• BLE scanning and connection management
• Text printing with full styling (bold, italic, underline, strikethrough)
• Rich text with mixed formatting in a single print
• Image printing with dithering, brightness/contrast adjustments
• QR codes and barcodes (CODE128, EAN13, UPC, etc.) — Android only
• Table/receipt layout printing
• Custom font support (TTF/OTF on Android, CSS font families on web)
• RTL text support
• Printer status (battery, paper, charging)
• Auto-reconnect (Android)
• Dry-run mode for testing
• 58mm and 80mm paper widths
• Web/PWA support via Web Bluetooth API

Platform Support

| Feature | Android | Web/PWA | |---|---|---| | BLE Scan | Background scan, returns device list | Browser device picker (user selects one) | | Connect / Disconnect | ✅ | ✅ | | Print Text | ✅ | ✅ | | Print Rich Text | ✅ | ✅ | | Print Image | ✅ | ✅ | | Print Table | ✅ | ✅ | | Print Barcode | ✅ | Use JS library + printImage | | Print QR Code | ✅ | Use JS library + printImage | | Preview | ✅ | ✅ (text, rich text, table, image) | | Auto-Reconnect | ✅ | Not supported | | Custom Fonts | TTF/OTF file path | CSS font family name | | Dry-Run Mode | ✅ | ✅ |

Web Bluetooth is supported in Chrome 56+, Edge 79+, Opera 43+, Samsung Internet 6.2+. Not supported in Safari or Firefox.

Install

npm install capacitor-cat-printer
npx cap sync android

Android Permissions

Add to AndroidManifest.xml before <application>:

<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />

Web Requirements

• HTTPS (required by Web Bluetooth API)
• A supported browser (Chrome, Edge, Opera)
• User interaction (click/tap) is required to trigger the BLE device picker

Quick Start

import { CatPrinter } from 'capacitor-cat-printer';

// Scan — on Android returns a list, on web opens browser device picker
const { devices } = await CatPrinter.scan({ duration: 5000 });

// Connect
await CatPrinter.connect({ address: devices[0].address });

// Print
await CatPrinter.printText({ text: 'Hello World!' });

// Disconnect
await CatPrinter.disconnect();

The same code works on both Android and Web. Capacitor automatically routes to the correct implementation.

API

Connection

// Scan for printers
const { devices } = await CatPrinter.scan({ duration: 5000 });
// devices: [{ name, address, rssi }]

// Stop scan early (no-op on web)
await CatPrinter.stopScan();

// Connect
await CatPrinter.connect({
  address: 'AA:BB:CC:DD:EE:FF',
  paperWidth: 384,        // 384 = 58mm, 576 = 80mm
  timeout: 10000,
  dryRun: false,          // true = simulate without printing
  autoReconnect: false    // Android only
});

// Check status
const { connected, address, paperWidth } = await CatPrinter.isConnected();

// Disconnect
await CatPrinter.disconnect();

Print Text

await CatPrinter.printText({
  text: 'Hello World!',
  fontSize: 24,
  align: 'center',        // 'left' | 'center' | 'right'
  bold: true,
  italic: false,
  underline: false,
  strikethrough: false,
  lineSpacing: 1.2,
  wordWrap: true,         // break at word boundaries
  rtl: false,             // right-to-left
  fontPath: '/path/to/font.ttf',  // Android: file path, Web: CSS font family
  energy: 0.6,            // 0.0-1.0 darkness
  quality: 3,             // 1-4
  feedAfter: 100
});

Rich Text (Mixed Formatting)

Print text with different styles in the same line:

await CatPrinter.printRichText({
  segments: [
    { text: 'Normal ' },
    { text: 'Bold', bold: true },
    { text: ' and ' },
    { text: 'Italic', italic: true },
    { text: ' Big', fontSize: 32 }  // per-segment font size
  ],
  fontSize: 24,
  align: 'left',
  lineSpacing: 1.2,
  rtl: false,
  fontPath: '/path/to/font.ttf',
  energy: 0.6,
  quality: 3,
  feedAfter: 100
});

Print Image

await CatPrinter.printImage({
  imageBase64: '...',     // base64 PNG/JPEG (no data: prefix)
  threshold: 127,         // 0-255 for B/W conversion
  dither: true,           // Floyd-Steinberg dithering
  brightness: 0,          // -100 to 100
  contrast: 0,            // -100 to 100
  invert: false,
  flipHorizontal: false,
  flipVertical: false,
  compress: false,        // for newer printers (GB03+)
  energy: 0.6,
  quality: 3,
  feedAfter: 100
});

QR Code (Android only)

await CatPrinter.printQRCode({
  data: 'https://example.com',
  size: 200,
  errorCorrection: 'M',   // 'L' | 'M' | 'Q' | 'H'
  align: 'center',
  energy: 0.6,
  feedAfter: 100
});

On web, generate the QR code with a library like qrcode and use printImage():

import QRCode from 'qrcode';
const base64 = await QRCode.toDataURL('https://example.com');
await CatPrinter.printImage({
  imageBase64: base64.replace('data:image/png;base64,', '')
});

Barcode (Android only)

await CatPrinter.printBarcode({
  data: '123456789',
  type: 'CODE128',        // CODE128, CODE39, EAN13, EAN8, UPC_A, UPC_E, ITF, CODABAR
  height: 80,
  showText: true,
  align: 'center',
  energy: 0.6,
  feedAfter: 100
});

On web, generate the barcode with a library like JsBarcode and use printImage().

Table / Receipt

await CatPrinter.printTable({
  rows: [
    { columns: [{ text: 'RECEIPT', align: 'center' }], bold: true, fontSize: 28 },
    { columns: [{ text: '─'.repeat(16), align: 'center' }] },
    { 
      columns: [
        { text: 'Item', width: 60 },           // width as percentage
        { text: 'Price', width: 40, align: 'right' }
      ], 
      bold: true 
    },
    { columns: [{ text: 'Coffee' }, { text: '$4.00', align: 'right' }] },
    { columns: [{ text: 'Muffin' }, { text: '$3.50', align: 'right' }] },
    { columns: [{ text: '─'.repeat(16), align: 'center' }] },
    { columns: [{ text: 'Total' }, { text: '$7.50', align: 'right' }], bold: true }
  ],
  fontSize: 22,
  showLines: false,       // horizontal lines between rows
  lineChar: '-',          // character for lines
  borderStyle: 'none',    // 'none' | 'all' | 'outer' | 'horizontal' | 'header'
  energy: 0.6,
  feedAfter: 100
});

Paper Control

await CatPrinter.feedPaper({ pixels: 100 });
await CatPrinter.retractPaper({ pixels: 50 });
await CatPrinter.cancelPrint();

Auto-Reconnect (Android only)

await CatPrinter.setAutoReconnect({
  enabled: true,
  maxAttempts: 3,
  delayMs: 2000
});

On web, this is a no-op. The browser manages BLE connection lifecycle.

Printer Info

// Get printer model
const model = await CatPrinter.getPrinterModel();
// { model: 'GB03', isNewKind: true, hasFeedingProblems: false, paperWidth: 384, deviceName: '...' }

// Get printer status
const status = await CatPrinter.getPrinterStatus();
// { connected, batteryLevel, isCharging, hasPaper, firmwareVersion, paperWidth }

// Get raw device info
const info = await CatPrinter.getDeviceInfo();

Preview (Without Printing)

const preview = await CatPrinter.getPreview({
  type: 'text',
  options: { text: 'Preview this', fontSize: 24 }
});
// { imageBase64, width, height }

Supported preview types: image, text, richtext, table. Barcode and QR code previews are Android only.

Events

// Device found during scan
CatPrinter.addListener('scanResult', (device) => {
  console.log('Found:', device.name, device.address);
});

// Connection state changed
CatPrinter.addListener('connectionState', (state) => {
  console.log('Connected:', state.connected);
});

// Print progress
CatPrinter.addListener('printProgress', (progress) => {
  console.log(`${progress.percent}% - ${progress.status}`);
  // status: 'processing' | 'printing' | 'feeding' | 'done' | 'error'
});

// Remove all listeners
await CatPrinter.removeAllListeners();

Platform Detection

import { Capacitor } from '@capacitor/core';

if (Capacitor.getPlatform() === 'web') {
  // Web: scan() opens browser device picker
  // Show a "Select Printer" button that triggers scan()
} else {
  // Android: scan() returns a list of nearby devices
  // Show a scanning UI with device list
}

Constants

import { PaperWidth, BarcodeType, PrinterModels } from 'capacitor-cat-printer';

PaperWidth.MM_58  // 384
PaperWidth.MM_80  // 576

BarcodeType.CODE128
BarcodeType.EAN13
// etc.

PrinterModels.GB01
PrinterModels.GB03
PrinterModels.MX05
// etc.

Supported Printers

Works with Cat thermal printers and compatibles using BLE characteristics:

• TX: 0000ae01-0000-1000-8000-00805f9b34fb
• RX: 0000ae02-0000-1000-8000-00805f9b34fb

Known models: GB01, GB02, GB03, GT01, MX05, MX06, MX08, MX09, MX10, MX11, YT01

Tips

• Enable Location Services for BLE scanning on Android
• Use energy: 0.6-0.8 for darker prints
• Enable dither: true for images with gradients
• Use quality: 4 for best quality (slower)
• Lower threshold = more black pixels in images
• On web, ensure your app is served over HTTPS
• On web, scan() must be triggered by a user gesture (click/tap)

License

MIT