rn-escpos-printer

Reliable ESC/POS Bluetooth printing for React Native on iOS and Android. The library owns discovery, connection lifecycle, image rasterization, command generation, write serialization, and Bluetooth backpressure without a closed vendor SDK.

Features

• Pure React Native TurboModule with autolinking
• Android Bluetooth Classic (RFCOMM/SPP) support
• iOS Bluetooth Low Energy support through writable GATT characteristics
• Paired-printer discovery on Android and timed BLE scanning on iOS
• Text printing with CP850 and Windows-1252 code pages
• Base64 image printing at the native 58 mm (384 px) or 80 mm (576 px) width
• Proportional image resizing without stretching
• Serialized native operations, connection timeouts, chunked writes, and BLE backpressure
• No Expo dependency and no proprietary printer SDK

Supported versions

Platform	Requirement	Transport
React Native	0.76 or newer	New Architecture/TurboModule
Android	API 24 or newer	Bonded Bluetooth Classic device with SPP/RFCOMM
iOS	The minimum supported by the host React Native version	BLE peripheral with a writable GATT characteristic

The printer must understand ESC/POS. iOS does not expose arbitrary Bluetooth Classic SPP devices, so the printer must offer BLE unless it is part of Apple's MFi program with a dedicated integration.

Installation

npm install rn-escpos-printer

or:

yarn add rn-escpos-printer

Install CocoaPods after adding the package:

cd ios && pod install

This package contains native code. It works with bare React Native apps and Expo development builds/prebuilds, but it cannot run inside Expo Go.

Native configuration

Android

The library manifest declares the Bluetooth permissions. On Android 12 (API 31) and newer, request BLUETOOTH_CONNECT before calling the library:

import { PermissionsAndroid, Platform } from 'react-native';

if (Platform.OS === 'android' && Platform.Version >= 31) {
  await PermissionsAndroid.request(
    PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT
  );
}

Pair the printer in Android system settings before discovery. getPrinters() intentionally returns bonded devices only; v1 does not request location or perform broad Android device discovery.

iOS

Add a Bluetooth usage description to Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Bluetooth is used to connect to your receipt printer.</string>

iOS returns a stable peripheral UUID as the printer id. Persist that value if the app should reconnect without scanning after a restart.

Quick start

import { EscPosPrinter, type PrinterDevice } from 'rn-escpos-printer';

await EscPosPrinter.initialize();

const printers: PrinterDevice[] = await EscPosPrinter.getPrinters({
  scanDurationMs: 4_000,
});

const printer = printers[0];
if (!printer) {
  throw new Error('No ESC/POS printer found');
}

await EscPosPrinter.connect(printer, { timeoutMs: 12_000 });

await EscPosPrinter.printText('Pedido 123\nTotal: R$ 42,90', {
  codePage: 'cp850',
  feedLines: 5,
  cut: true,
});

await EscPosPrinter.printImageBase64(receiptPngBase64, {
  paperWidth: 80,
  threshold: 160,
  feedLines: 5,
  cut: true,
});

await EscPosPrinter.disconnect();

printImageBase64 accepts either a raw base64 payload or a data:image/...;base64,... URI.

API

initialize(): Promise<void>

Validates Bluetooth availability and permission. Call it before discovery or connection so configuration failures are reported early.

getPrinters(options?): Promise<PrinterDevice[]>

On Android, returns bonded Bluetooth devices immediately. On iOS, scans for named BLE peripherals for scanDurationMs (default: 4000 ms).

type PrinterDevice = {
  id: string;
  name: string;
  address: string;
  transport: 'bluetooth-classic' | 'ble';
  connected: boolean;
};

connect(printer, options?): Promise<void>

Accepts a PrinterDevice or its id. The default timeout is 12 seconds. The promise resolves only after Android opens the SPP socket or iOS discovers a writable characteristic.

disconnect(): Promise<void>

Closes the active connection and clears native transport state.

isConnected(): Promise<boolean>

Returns whether a usable native printer transport is active.

printText(text, options?): Promise<void>

Option	Type	Default
codePage	'cp850' | 'cp860' | 'windows1252'	'cp850'
feedLines	integer from 0 to 10	5
cut	boolean	true

The printer's configured character table must match the selected code page. CP850 remains the backward-compatible default. For Portuguese receipts, use CP860 when the printer supports the standard ESC/POS page 3 mapping:

await EscPosPrinter.printText('Não autorizado: ação e preço', {
  codePage: 'cp860',
});

Character-table support and page numbers can vary on non-Epson-compatible firmware, so validate the selected code page on every printer model used in production.

printImageBase64(base64, options?): Promise<void>

Option	Type	Default
paperWidth	58 | 80	80
threshold	integer from 0 to 255	160
feedLines	integer from 0 to 10	5
cut	boolean	true

Images are decoded and rasterized natively. They are resized to 384 or 576 pixels with the original aspect ratio, converted to monochrome, and sent with the widely supported ESC * 24-dot bit-image command.

Error handling

Rejected native promises expose one of these stable error codes through error.code:

• ERR_BLUETOOTH_DISABLED
• ERR_BLUETOOTH_PERMISSION
• ERR_CONNECTION_FAILED
• ERR_CONNECTION_LOST
• ERR_CONNECTION_TIMEOUT
• ERR_INVALID_ARGUMENT
• ERR_INVALID_IMAGE
• ERR_NOT_CONNECTED
• ERR_PRINTER_NOT_FOUND
• ERR_SCAN_FAILED
• ERR_WRITE_FAILED

try {
  await EscPosPrinter.connect(printer);
} catch (error) {
  const code =
    error instanceof Error && 'code' in error ? error.code : undefined;
  console.error(code, error);
}

Scope of v1

Version 1 is intentionally limited to the production needs that motivated the package:

• Bluetooth transport only
• ESC/POS printers only
• Text and base64 images only
• 58 mm and 80 mm paper

USB, TCP/IP, QR codes, barcodes, cash drawers, printer status queries, and vendor-specific protocols are not part of v1.

Printer compatibility

ESC/POS describes the print command language, while each printer also chooses a Bluetooth profile, GATT service, characteristic, buffer size, cutter, and character-table mapping. The library uses standard SPP on Android and dynamically discovers writable GATT characteristics on iOS, with conservative chunking and flow control.

For a production rollout, validate every printer model and firmware revision used by the business. When reporting a compatibility issue, include the platform, OS version, printer model, firmware, advertised BLE services/characteristics (iOS), and a minimal print payload.

Development

See CONTRIBUTING.md for the local workflow and docs/architecture.md for implementation details.

yarn
yarn verify

License

MIT © HighSoft Sistemas