The Cat Printer SDK is a powerful JavaScript library that brings the convenience of Bluetooth connectivity to your web applications. Connect to affordable portable mini thermal printers (commonly known as Cat Printers) to print text, images, and more programmatically without using the vendor's mobile app.
⚠️ Warning: This library has been tested only on select printer models. We highly recommend trying the demo to verify compatibility before deploying in production.
- Bluetooth Connectivity: Easily connect to your thermal printer using Web Bluetooth.
- Text Printing: Customize font family, size, weight, alignment, and more for professional output.
- Image Printing with Multiple Dithering Methods: Convert images to black and white using various methods:
- Threshold: Simple brightness cutoff.
- Bayer: Uses an ordered Bayer matrix for a patterned effect.
- Floyd-Steinberg: Implements error diffusion for smoother gradients.
- Dot Dithering: Additional technique for more artistic or technical effects.
- Printer Control: Adjust print settings such as speed, energy, and paper feed.
- State Monitoring: Check printer conditions like paper status, cover position, temperature, battery level, and more.
- Queue Support: Manage and print multiple items in sequence to streamline your printing workflow.
Get started in seconds by installing the Cat Printer SDK using your favorite package manager:
npm install @opuu/cat-printeryarn add @opuu/cat-printerpnpm add @opuu/cat-printerbun add @opuu/cat-printerBelow is a simple example demonstrating how to connect to a Cat Printer, print text and an image, and then gracefully disconnect.
import{CatPrinter}from'@opuu/cat-printer';// Create a new instance with debug logging enabledconstprinter=newCatPrinter({debug: true});// Connect to the printerasyncfunctionconnectPrinter(){try{awaitprinter.connect();console.log('Connected to printer!');// Print text with custom optionsawaitprinter.printText('Hello World!',{fontSize: 24,fontWeight: 'bold',align: 'center',lineSpacing: 8});// Print an image using Floyd-Steinberg ditheringawaitprinter.printImage('https://example.com/image.jpg',{dither: 'floyd-steinberg'});// Feed the paper to finalize the printing jobawaitprinter.feed(100);// Disconnect when the job is doneawaitprinter.disconnect();}catch(error){console.error('Error during printing:',error);}}// Bind the connect function to a button click eventdocument.getElementById('connectButton').addEventListener('click',connectPrinter);The CatPrinter class offers all methods needed to interact with a thermal printer via Bluetooth.
newCatPrinter(options?: PrinterOptions)PrinterOptions:
| Option | Type | Default | Description |
|---|---|---|---|
| debug | boolean | false | Enable debug logging |
| speed | number | 32 | Default print speed |
| energy | number | 24000 | Default print energy/density |
| finishFeed | number | 100 | Default lines to feed after printing |
connect(): Promise
Connects to the printer via Bluetooth.disconnect(): Promise
Disconnects from the printer.isConnected(): boolean
Returns the current connection status.getState(): PrinterState
Retrieves detailed printer state.
printText(text: string, options?: TextOptions): Promise
Prints text with customizable formatting.printImage(imageUrl: string, options?: ImageOptions): Promise
Prints an image using a specified dithering method.printMultiple(items: Array<{type: 'text' | 'image', content: string, options?: TextOptions | ImageOptions}>): Promise
Prints multiple items in a queued sequence.
feed(lines: number): Promise
Advances the paper by the specified number of lines.retract(lines: number): Promise
Retracts available paper by the given number of lines.
setSpeed(speed: number): Promise
Adjusts the printing speed.setEnergy(energy: number): Promise
Adjusts the print energy/density.prepare(speed: number, energy: number): Promise
Sets up both speed and energy simultaneously.finish(feed: number): Promise
Completes printing with a final paper feed.
| Option | Type | Description |
|---|---|---|
| fontFamily | string | Font family for the text |
| fontSize | number | Font size in pixels |
| fontWeight | string | Font weight (e.g., 'normal', 'bold') |
| align | 'start' | 'center' | 'end' | 'justified' | Text alignment |
| lineSpacing | number | Line spacing in pixels |
| rotate | number | Rotation angle in degrees |
| flipH | boolean | Flip text horizontally |
| flipV | boolean | Flip text vertically |
| brightness | number | Brightness threshold (0-255) |
| offset | number | Optional paper feed/retract adjustment |
| Option | Type | Description |
|---|---|---|
| dither | 'none' | 'threshold' | 'bayer' | 'floyd-steinberg' | 'dot' | Dithering algorithm to convert images |
| rotate | number | Rotation angle in degrees |
| flipH | boolean | Flip the image horizontally |
| flipV | boolean | Flip the image vertically |
| brightness | number | Brightness threshold (0-255) |
| offset | number | Paper feed/retract adjustment before printing |
| Property | Type | Description |
|---|---|---|
| outOfPaper | boolean | True when the printer is out of paper |
| coverOpen | boolean | True when the printer's cover is open |
| overheat | boolean | True when the printer is overheated |
| lowPower | boolean | True when the battery is low |
| paused | boolean | True when the printer is paused |
| busy | boolean | True when the printer is busy |
When printing images, the SDK converts images to black and white using various dithering techniques. Each method offers a unique visual style and performance characteristics:
- threshold: Applies a simple brightness threshold.
- bayer: Uses an ordered Bayer matrix to generate a patterned effect.
- floyd-steinberg: Uses error diffusion for smooth gradient transitions.
- dot: Additional technique offering distinct stylistic results; ideal for creative outputs.
Below are previews showcasing the visual effects of different dithering methods. (Note: Replace the image URLs with actual examples as needed.)
| Dithering Method | Preview |
|---|---|
| None |  |
| Threshold |  |
| Bayer |  |
| Floyd-Steinberg |  |
| Dot |  |
The Cat Printer SDK leverages the Web Bluetooth API, which is currently supported in:
- Chrome
- Edge
- Opera
Please note that Safari and Firefox do not offer native support for the Web Bluetooth API, all chromium-based browsers should work fine.
We welcome contributions! If you have suggestions, bug reports, or feature requests, please open an issue or submit a pull request.
- GB01
- GB02
- GB03
- GT01
- YT01
- MX05
- MX06
- MX08
- MX10
- X5
Distributed under the AGPL-3.0 license. See the LICENSE file for details.