🖨️ Capacitor USB Printer Plugin

A Capacitor plugin that allows Android apps to print receipts or images directly to a USB thermal printer using the ESC/POS command set.
Supports both PNG/JPEG and SVG (base64) formats.

📦 Installation

npm i @atomsolution/usb-printer-capacitor
npx cap sync

⚙️ Android Setup

This plugin depends on the DantSu ESC/POS Thermal Printer library, distributed via JitPack.
Add this line to your root android/build.gradle file:

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

💡 Usually located at android/build.gradle (not inside app/).

🚀 Usage

1. Import the Plugin

import { UsbPrinter } from "@atomsolution/usb-printer-capacitor";

2. Connect to the USB Printer

async function connectPrinter() {
  try {
    await UsbPrinter.connect();
    console.log('✅ Connected to USB printer');
  } catch (err) {
    console.error('❌ Failed to connect:', err);
  }
}

3. Print Text

await UsbPrinter.printText({
  text: 'Hello from Capacitor USB Printer ✅\n\n',
});

4. Print Base64 Image (PNG / JPG / SVG)

You can print base64-encoded images (including SVG):

await UsbPrinter.printBase64({
  data: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...',
});

or:

await UsbPrinter.printBase64({
  data: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDov...',
});

💡 Example React + Capacitor App

Here’s a simple example UI you can include in your React app (e.g. src/App.tsx) to test connection and printing:

import React, { useState } from 'react';
import { UsbPrinter } from "@atomsolution/usb-printer-capacitor";

function App() {
  const [status, setStatus] = useState('Not connected');

  const connect = async () => {
    try {
      await UsbPrinter.connect();
      setStatus('✅ Connected');
    } catch (e) {
      setStatus('❌ Connection failed');
    }
  };

  const printText = async () => {
    try {
      await UsbPrinter.printText({ text: 'Hello World!\nFrom Capacitor 🖨️' });
      alert('Printed successfully!');
    } catch (e) {
      alert('Print failed: ' + e);
    }
  };

  const printImage = async () => {
    try {
      const base64 = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...'; // your image
      await UsbPrinter.printBase64({ data: base64 });
      alert('Image printed!');
    } catch (e) {
      alert('Print failed: ' + e);
    }
  };

  return (
    <div style={{ padding: 20, fontFamily: 'sans-serif' }}>
      <h2>🖨️ Capacitor USB Printer Demo</h2>
      <p>Status: {status}</p>
      <button onClick={connect}>Connect Printer</button>
      <button onClick={printText}>Print Text</button>
      <button onClick={printImage}>Print Image</button>
    </div>
  );
}

export default App;

💡 You can run this with npm start and test on your connected Android device via npx cap open android.

🧾 Supported Printers

Tested with:

• XPrinter XP-N160I / XP-58 / XP-80
• Rongta RP80
• Zjiang ZJ-5890 / ZJ-80
• Any printer supporting ESC/POS USB

⚙️ Printer Configuration

| Setting | Default | Description | |----------|----------|-------------| | DPI | 203 | Printer resolution | | Paper Width | 72f mm | Physical paper width | | Printable Width | auto-calculated | Fitted to printer width | | Output | Monochrome | Dithered bitmap for better contrast |

🧠 Notes

• Works on Android 5.0 (Lollipop) and above.
• Requires USB Host mode on the device.
• Automatically asks for USB permission.
• Supports PNG, JPEG, and SVG base64 formats.
• Automatically scales and pads width to prevent skew or cutoff.

🧰 Troubleshooting

| Issue | Possible Fix | |--------|----------------| | Printer not connected | Ensure printer is powered on and permission granted | | Failed to decode image data | Verify correct base64 prefix | | Image shifted or cropped | Adjust paperWidthMM in plugin | | Faint output | Use higher contrast or adjust printer density |

🧑‍💻 Development

If you’re building the plugin locally:

# Inside plugin folder
npm run build

# Link with your Capacitor app
npx cap sync android

Then open the Android Studio project:

npx cap open android

📜 License

MIT License © 2025

❤️ Credits

• Built with Capacitor Plugin API
• Maintained with ❤️ by LUBAN team