🧾 React POS Engine

Overview

React POS Engine is your complete solution for POS and invoice printing in React applications. Built with TypeScript and modern best practices, it offers:

• 🖨️ Print-Ready Templates: 20 professional templates for various business needs
• 🎨 Customization: Full control over styling, layouts, and branding
• 📱 Responsive: Works with any paper size from 58mm POS rolls to A4
• 🚀 Simple Integration: Easy-to-use React Hook (useReceiptPrint)
• 💪 Type-Safe: Built with TypeScript for reliable development

📑 Table of Contents

1. ✨ Features
2. 🛠️ System Requirements
3. 📦 Getting Started
   • Installation
   • Basic Setup
4. � Usage Guide
   • Quick Start
   • Configuration Options
5. 📋 API Reference
   • Type Definitions
   • Hooks Documentation
6. 🎨 Layout Templates
7. 🤝 Contributing
8. 📄 License

✨ Features

Core Capabilities

📑 Template System

• 20 Professional Layouts
  • Retail POS receipts
  • Restaurant orders and kitchen tickets
  • Service invoices and estimates
  • Digital receipts and e-commerce
  • Specialized formats (gift receipts, returns)

🎨 Styling & Customization

• Brand Identity Control
  • Custom colors and typography
  • Logo placement options
  • Flexible layout adjustments
• CSS Flexibility
  • Direct CSS customization
  • Theme support
  • Responsive design

🖨️ Print Management

• Paper Size Support
  • 58mm/80mm POS rolls
  • A4/Letter documents
  • Custom size configuration
• Professional Output
  • Controlled print dialog
  • Preview functionality
  • High-quality rendering

💻 Developer Tools

• TypeScript Integration
  • Full type safety
  • IntelliSense support
  • Documentation
• React Integration
  • Hooks-based API
  • Preview components
  • Real-time updates

🛠️ System Requirements

Required Software

• Node.js: v14 or higher
• React: v16.8+ (Hooks support required)
• Browser: Modern browser with ES6 support

Development Environment

• TypeScript 4.0+ (recommended)
• npm, yarn, or pnpm
• VS Code (recommended for TypeScript support)

Optional Tools

• Chrome DevTools for print preview
• React Developer Tools for component debugging

📦 Getting Started

Installation

Install the package using your preferred package manager:

# Using npm
npm install react-pos-engine



### Basic Setup

1. **Import the Package**

```typescript
import { useReceiptPrint } from "react-pos-engine";

2. Configure Types (TypeScript)

import type { Order, PrintOptions } from "react-pos-engine";

3. Add to Your Project

// See usage examples below for implementation details

� Usage Guide

Quick Start

The useReceiptPrint hook is the core of React POS Engine. It handles:

• Receipt data processing
• Style customization
• Print dialog management
• Preview rendering

Example Data Structure

// Example mock order for testing
const MOCK_ORDER: Order = {
  id: "BRN-2023001",
  date: Date.now(),
  items: [
    { name: "Premium T-Shirt (L)", price: 2999, quantity: 1 },
    { name: "Bornosoft Sticker Pack", price: 499, quantity: 2 },
    { name: "Developer Mug", price: 1499, quantity: 1 },
    { name: "React Native Pin", price: 799, quantity: 3 },
    { name: "Tech Sticker", price: 299, quantity: 2 },
  ],
  subtotal: 7892,
  tax: 789,
  total: 8681,
  customer: {
    name: "Kazi Nayeem",
    address: "123 Tech Avenue, Dhaka",
    phone: "+880-1234567890",
    email: "[email protected]",
  },
  customFields: [
    { key: "Cashier", value: "NAYEEM-001" },
    { key: "Order Type", value: "In-Store" },
    { key: "Member", value: "Gold" },
  ],
  notes: "Thank you for shopping with Bornosoft!",
  loyaltyPoints: 100,
};

Basic Implementation Example

import React, { useMemo } from 'react';
import { useReceiptPrint, type Order, type PrintOptions } from 'react-pos-engine';

const ReceiptPrintButton = ({ currentOrder }: { currentOrder: Order }) => {
  const printOptions: PrintOptions = useMemo(() => ({
    layout: 2,                // Layout 2: Detailed POS w/ Custom Fields
    alignment: 'center',
    primaryColor: '#2563EB',
    textColor: '#000000',
    paperSize: '80mm',       // Standard 80mm receipt paper
    customCss: '',          // Optional custom styles
    baseFontSize: 12,
    fontFamily: 'Arial',
  }), []);

  const { printReceipt, ReceiptContent } = useReceiptPrint(currentOrder, printOptions);

  return (
    <div>
      {/* Preview Component (Optional) */}
      <ReceiptContent order={currentOrder} {...printOptions} />

      {/* Print Trigger Button */}
      <button
        onClick={printReceipt}
        disabled={!currentOrder.items.length}
      >
        Print Receipt
      </button>
    </div>
  );
};

export default ReceiptPrintButton;





## 📋 API Reference

### Type Definitions

#### 🛍️ Order Interface
The core data structure for receipt content:

```typescript
interface Item {
  name: string;
  price: number;      // in cents
  quantity: number;
}

interface Customer {
  name: string;
  address: string;
  phone: string;
  email: string;
}

interface Order {
  id: string;
  date: number;       // Timestamp
  items: Item[];
  subtotal: number;
  tax: number;
  total: number;
  customer: Customer;
  customFields: Array<{
    key: string;
    value: string;
  }>;
  notes: string;
  loyaltyPoints?: number;
}

⚙️ PrintOptions Interface

Customize the appearance and behavior of your receipts:

interface PrintOptions {
  layout: number;     // 1-20 (see layouts table below)
  paperSize: '58mm' | '80mm' | '100mm' | 'a4' | 'letter';
  alignment: 'start' | 'center' | 'end';
  primaryColor: string;
  baseFontSize: number;
  fontFamily: string;
  textColor?: string;
  logoUrl?: string;
  sellerName?: string;
  showSignature?: boolean;
  showTaxBreakdown?: boolean;
  showCustomerPhone?: boolean;
  showNotes?: boolean;
  customCss?: string;
}



## 🎨 Layouts (1–16)

This project ships a curated set of professional layouts tailored to common POS, restaurant, e-commerce and invoicing needs. You can switch between them by setting the `layout` property in `PrintOptions` (1–16). Below is a concise, developer-friendly reference so you can pick the right layout quickly.

How to switch: pass `layout` to the `useReceiptPrint` hook or `ReceiptContent` component.

```tsx
// Switch to layout 9
const options = { layout: 9, /* other options */ };
<ReceiptContent order={order} {...options} />
```

Summary of layouts (1–16):

- 1 — Classic POS: Clean retail receipt with clear totals and store header; ideal for small shops.
- 2 — Modern Grid / Detailed POS: Wider layout with custom fields and extended details for professional receipts.
- 3 — Dark Mode / Minimalist: Compact, low-ink design focused on essentials and fast printing.
- 4 — Standard Invoice (A4): Full A4 invoice with billing section, signature block and totals — suitable for formal invoices.
- 5 — Stacked Summary: Emphasizes order summary blocks and large total display for quick checks.
- 6 — Kitchen Ticket: No prices, large quantities and simple lines for kitchen staff printing.
- 7 — Promotion / Pickup Slip: Promotional banner area and prominent offer blocks — good for marketing slips.
- 8 — Financial Invoice: Finance-style layout with clear reference and date blocks for accounting copies.
- 9 — Sleek Underline: Modern receipt with decorative underlines and strong typographic hierarchy.
- 10 — Pill Header: Rounded pill-style header for stylish, attention-grabbing tickets.
- 11 — Split Header: Two-column split header for reference/customer info and time, ideal for service tickets.
- 12 — Boxed Summary: Totals wrapped in boxed panels — great for returns/credit slips.
- 13 — Item Emphasis: Emphasizes item names and per-item totals for clarity in detailed receipts.
- 14 — E-Commerce / Shipping: Includes shipping block, tracking ID and customer address for online orders.
- 15 — Minimalist POS: A very spare, readable layout for compact printers and mobile receipts.
- 16 — Vibrant Tropical: Color-forward template with accent bands — useful for brands that want visual flair.

Pro tip: layouts 1–3 and 9–16 are optimized for typical POS roll widths (58/80mm); layout 4 targets A4/Letter documents and will be rendered as a full-page invoice.

Demo screenshot

You provided a demo screenshot; include it in docs like this for marketing or README usage:

![Demo Screenshot](https://i.ibb.co.com/6RCnnhNp/Screenshot-2025-11-04-200216.png)

If the image doesn't render, try uploading the file to a public host (Imgur / i.ibb.co) and replace the link above.

Quick examples — switching layout programmatically

```tsx
// Example: change layout at runtime in your app
const [layout, setLayout] = useState<number>(1);

// toggling
<select value={layout} onChange={(e) => setLayout(Number(e.target.value))}>
  {Array.from({ length: 16 }).map((_, i) => (
    <option key={i} value={i + 1}>Layout {i + 1}</option>
  ))}
</select>

// pass to hook / component
const options = { layout };
<ReceiptContent order={order} {...options} />
```

Advanced styling and customization

- Colors: set `primaryColor` and `borderColor` in `PrintOptions`.
- Paper sizes: use `paperSize` (`58mm`, `80mm`, `a4`, etc.). Layout 4 (A4 invoice) is rendered full-page.
- Brand: supply `logoUrl`, `headerText`, and `sellerName` to tailor the output.

Want a gallery page? See `src/components/DemoContainer.tsx` — you can create a small `LayoutGallery` component that renders `ReceiptContent` for layouts 1–16 to let stakeholders preview all templates. (This is a recommended next step.)

---


## 🤝 Contributing

### How to Contribute

We love your input! We want to make contributing to React POS Engine as easy and transparent as possible.

1. 🍴 Fork the repository
2. 🌿 Create your feature branch
   ```bash
   git checkout -b feature/AmazingFeature

3. 💻 Make your changes
4. ✅ Commit with clear messages

   git commit -m 'Add: Amazing Feature'

5. 🚀 Push to your branch

   git push origin feature/AmazingFeature

6. 🔄 Open a Pull Request

Reporting Issues

Found a bug? We're here to help! Please include:

For Bug Reports 🐛

• Detailed description of the problem
• Clear steps to reproduce
• Expected vs actual behavior
• Environment details:
  • React version
  • Browser & version
  • Node.js version
  • Operating system

For Feature Requests 💡

• Clear use case description
• Example scenarios
• Potential implementation ideas (optional)

Screenshort

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Support

If you find this project helpful, please consider:

• Giving it a star ⭐
• Sharing it with others 🔄
• Contributing to its improvement 🤝

Documentation · Report Bug · Request Feature · npm Package