📦 @stratametriq/id-card-designer

A universal, dynamic, and highly customizable ID Card Designer & Batch Print Dashboard for React, Vue, Angular, and Vanilla JS.

Whether you are building a Student Information System, HR Employee Directory, or Event Badge Generator, this package gives your users a professional visual canvas to design, customize, preview, and batch export PVC ID cards directly inside your app.

📑 Table of Contents

• Installation
• Quick Start
• Features
• Props
• Templates
• Customization
• Events
• Examples
• FAQ
• License

💻 Installation

Install the package using NPM or Yarn:

npm install @stratametriq/id-card-designer
# or
yarn add @stratametriq/id-card-designer

⚡ Quick Start

🚀 Try the Live Interactive Demo on StackBlitz

You can launch a complete ID card design studio and batch print dashboard with just two lines of code. It comes with pre-built dummy data so you can test it immediately!

import { IdCardManager } from '@stratametriq/id-card-designer';
import '@stratametriq/id-card-designer/dist/index.css';

export default function App() {
  // This will render the complete turnkey dashboard with demo data!
  return <IdCardManager />;
}

🌟 Features

• 🎨 Turnkey Dashboard: A complete workspace with department tabs, vector stage, and batch printing ready out-of-the-box.
• 📥 Batch CSV Import: Let users upload spreadsheets to instantly generate hundreds of cards.
• 🔳 QR & Barcodes: Built-in dynamic 1D Barcode and 2D QR Code generation.
• 🏷️ Variable Placeholders: Easily map database fields to card text (e.g., ID: {{admissionNo}}).
• 🖼️ High-Res PDF/PNG Export: Batch export to A3/A4/A5/Letter size PDF sheets with hardware cut marks.
• 🌐 Framework Agnostic: Works natively with React and Next.js, and easily mounts into Vue, Angular, and Vanilla HTML.

⚙️ Props

The main <IdCardManager /> component accepts the following props:

| Prop | Type | Default | Description | |---|---|---|---| | sampleRecords | object | default data | Pass your own database records to populate the dashboard. | | categories | object | default config | Custom category definitions for different ID types. | | onBatchExportComplete | function | undefined | Callback fired when PDF generation completes. |

Standalone <IdCardDesigner /> Props

If you are using the standalone designer component directly, you can pass these props to configure the editor:

<IdCardDesigner
    width={350}
    height={200}
    template={template}
    onSave={handleSave}
    onExport={handleExport}
/>

🧩 Templates

Designs are saved and loaded as clean JSON schemas.

{
  "id": "tpl_school_vertical_01",
  "orientation": "vertical",
  "width": 54,
  "height": 86,
  "elements": [
    {
      "id": "el_student_name",
      "type": "field",
      "fieldKey": "studentName",
      "label": "Student Name",
      "x": 2, "y": 48, "width": 50, "height": 7
    }
  ]
}

🎨 Customization

You can define custom categories to control exactly what fields your ID cards should support.

const myCategories = {
  university: {
    id: "university",
    label: "University Students",
    fieldDefinitions: [
      { key: "studentName", label: "Student Full Name" },
      { key: "enrollmentNo", label: "Enrollment Number" }
    ]
  }
};

<IdCardManager categories={myCategories} />

Modular Components

If you don't want the full dashboard, you can use our modular components:

• <IdCardPreview />: Embed a live ID card directly on a user profile page.
• <IdCardDesignerModal />: Open the drag-and-drop design studio inside your own popup.
• generateIdCardsPdf(): Trigger a high-resolution PDF export programmatically.

📡 Events

You can hook into various lifecycle and user action events across the components:

<IdCardManager /> Events

• onBatchExportComplete(category, records): Fired when a user successfully exports a batch of IDs to PDF.

<IdCardDesigner /> Events

• onSave(templateData): Fired when the user clicks the save button. Returns the full JSON schema of the current design.
• onExport(format, data): Fired when an export action is triggered (e.g., exporting a single card to PNG or PDF).
• onChange(elementData): Fired continuously as the user drags, resizes, or modifies elements on the canvas.
• onDelete(elementId): Fired when a specific element is deleted from the canvas.
• onTemplateChange(templateId): Fired when the user switches to a different template.

💡 Examples

Connect Your Own Data (React)

import { IdCardManager } from '@stratametriq/id-card-designer';
import '@stratametriq/id-card-designer/dist/index.css';

export default function MyPortal() {
  const myRealStudents = [
    { studentName: "Aarav Sharma", admissionNo: "101", bloodGroup: "O+" },
    { studentName: "Diya Patel", admissionNo: "102", bloodGroup: "B+" }
  ];

  return (
    <IdCardManager sampleRecords={{ student: myRealStudents }} />
  );
}

Mounting in Vue, Angular, or Vanilla HTML

<div id="id-card-manager-root"></div>
<script type="module">
  import React from 'react';
  import { createRoot } from 'react-dom/client';
  import { IdCardManager } from '@stratametriq/id-card-designer';
  import '@stratametriq/id-card-designer/dist/index.css';

  const root = createRoot(document.getElementById('id-card-manager-root'));
  root.render(React.createElement(IdCardManager));
</script>

❓ FAQ & Comparisons

Q: How is this different from Canva?
A: Canva is fantastic for creating manual, one-off designs. However, if you need to generate 500 student ID cards with unique photos, barcodes, and names, Canva becomes tedious. This package is an automation pipeline—you design the template once, feed it an array of JSON data, and instantly generate thousands of unique cards.

Q: Why not just use standard HTML-to-Image libraries directly?
A: Building a production-ready ID card designer from scratch using standard HTML-to-canvas libraries is incredibly frustrating. You have to handle exact hardware printing dimensions (like CR80 PVC card aspect ratios), perfect image scaling, drag-and-drop boundary logic, and multi-page A4 PDF rendering with precise cut-marks. We've solved all of that complex math for you out-of-the-box.

Q: How does this compare to enterprise desktop ID software?
A: Traditional ID software usually requires heavy Windows installations and expensive per-seat licenses. This package allows you to bring that exact same enterprise-level design capability directly into your web app as a lightweight React component that works on Mac, Windows, and Linux.

Q: Does our sensitive data leave our servers?
A: Absolutely not. Employee and student data (PII) is a massive security concern. That is why this engine runs 100% Client-Side in the browser. Zero network requests are made to external servers. The PDFs and images are generated purely on the user's local machine.

Q: Can I remove your branding? (White-labeling)
A: Yes! The enterprise license is 100% white-label, allowing you to seamlessly integrate the designer into your own SaaS product without your users ever knowing you are using our software.

📜 License

@stratametriq/id-card-designer is dual-licensed:

1. Community / Open Source Tier (MIT License): Free for non-commercial evaluation and personal open-source projects. See MIT License.
2. Commercial / Enterprise Tier: Required for commercial SaaS applications, School ERPs, HR suites, and production use.

👉 Purchase a Commercial Enterprise License to Unlock Production Usage & Priority Support