📦 react-id-card-designer

A universal, dynamic, and highly customizable ID Card Designer & A4 Multi-Page PDF Rendering Engine for React.

Whether you are building an HR Employee Directory, School/University Student Information System, Event Badge Generator, or Membership Club Portal, react-id-card-designer gives your users a professional visual canvas right inside your application to design, customize, preview, and batch export PVC ID cards.

🌟 Features

• 🎨 Interactive Visual Canvas: Drag-and-drop element positioning (react-draggable), real-time zoom controls (25% - 200%), grid snapping (1mm / 5mm), and Z-index layering.
• 🔄 Undo & Redo History Control: Full history stack tracking (Ctrl+Z / Cmd+Z to undo, Ctrl+Y / Cmd+Shift+Z to redo) alongside keyboard arrow key precision nudging (1px or 5px with Shift).
• 📝 Signature & Image File Uploads: Upload Principal signatures, student photos, or school logos (PNG/JPG) directly from the property inspector with live base64 conversion and preview.
• 🔄 Multi-Orientation Support: Seamless switching between standard PVC card dimensions: Vertical (54×86 mm) and Horizontal (86×54 mm).
• ⚡ Professional Built-in Presets: Starter templates including Classic Traditional, Minimalist Modern, Sage Table Banner, and Modern Sidebar.
• 🧩 Universal Element Types: Dynamic text fields, static labels, custom shapes/dividers, profile photos, organization logos, signature slots, and visual barcodes/QRs.
• 🔍 Inspector Panel & Property Editor: Fine-grained styling for font family, size, weight, text alignment, text casing (uppercase, lowercase, capitalize, togglecase), background/border colors, radii, prefixes/suffixes, and divider underlines.
• 📄 High-Resolution Batch PDF Export: Built-in multi-page A4 grid layout calculation and high DPI (html2canvas + jspdf) rendering engine.

📦 Installation

npm install react-id-card-designer
# or
yarn add react-id-card-designer

Include the stylesheet in your project root (main.jsx or App.jsx):

import "react-id-card-designer/dist/index.css";

📖 Public API Reference

1. <IdCardDesignerModal />

The primary interactive modal component for designing and modifying ID card templates.

| Prop Name | Type | Default | Description | | :--- | :--- | :--- | :--- | | show | boolean | false | Controls visibility of the designer modal. | | onHide | function | () => {} | Callback triggered when closing the modal. | | initialOrientation | string | "vertical" | Default card orientation ("vertical" | "horizontal"). | | initialTemplate | object | null | Existing JSON template schema to edit. If null, loads preset. | | fieldDefinitions | array | [] | Array of dynamic field options ([{ key, label, defaultValue }]). | | sampleData | array | [] | Array of data records to preview during designing. | | themeColors | object | { primary: "#424343", text: "#faf4f4" } | Default primary header and text colors. | | orgAssets | object | { logoUrl, signatureUrl, defaultAvatarUrl } | Default image URLs for logo, signature, and fallback photo. | | onSaveTemplate | function | (templateSchema) => {} | Callback returning the finalized JSON template object on save. |

2. <IdCardPreview />

A lightweight component for rendering a single ID card anywhere in your UI.

| Prop Name | Type | Default | Description | | :--- | :--- | :--- | :--- | | templateSchema | object | Required | The JSON template schema generated by the designer. | | data | object | {} | The record object containing dynamic field values to display. | | orientation | string | "vertical" | Orientation ("vertical" or "horizontal"). | | zoom | number | 1 | Scaling factor (1 = exact physical dimensions, 1.5 = 150% size). | | className | string | "" | Optional CSS class name for outer wrapper. |

3. generateIdCardsPdf(options)

An asynchronous utility function to generate multi-page, high-resolution A4 PDFs for batch printing.

import { generateIdCardsPdf } from "react-id-card-designer";

await generateIdCardsPdf({
  records: [...],             // Array of data records to render
  templateSchema: {...},      // JSON template schema object
  orientation: "vertical",    // "vertical" | "horizontal"
  fileName: "ID_Cards.pdf",   // Name of the downloaded file
  pageOptions: {
    format: "a4",             // Paper size ("a4" | "letter")
    scale: 2,                 // Resolution scale for html2canvas (2 = High DPI)
    marginMm: 10,             // Top/side page margins in mm
    spacingMm: 10             // Gap between cards in mm
  },
  onProgress: (current, total) => {
    console.log(`Rendered page ${current} of ${total}`);
  }
});

4. JSON Template Schema Structure (templateSchema)

Every design created in <IdCardDesignerModal /> is stored and exported as a clean, serializable JSON schema. Understanding its format allows you to programmatically create or modify templates before rendering:

{
  "id": "tpl_school_vertical_01",
  "name": "Classic School Vertical ID",
  "orientation": "vertical",
  "width": 54,
  "height": 86,
  "elements": [
    {
      "id": "el_header_box",
      "type": "shape",
      "label": "Top Header Box",
      "x": 0, "y": 0, "width": 54, "height": 14,
      "backgroundColor": "#0d6efd",
      "zIndex": 1
    },
    {
      "id": "el_photo_slot",
      "type": "image",
      "subtype": "photo",
      "fieldKey": "profilePhoto",
      "label": "Student Photo",
      "x": 14, "y": 18, "width": 26, "height": 28,
      "borderWidth": 1.5, "borderColor": "#0d6efd", "borderRadius": 4,
      "zIndex": 3
    },
    {
      "id": "el_student_name",
      "type": "field",
      "fieldKey": "studentName",
      "label": "Student Name",
      "x": 2, "y": 48, "width": 50, "height": 7,
      "fontFamily": "Inter, sans-serif",
      "fontSize": 11, "fontWeight": "bold", "color": "#111111",
      "textAlign": "center", "textTransform": "uppercase",
      "zIndex": 4
    },
    {
      "id": "el_principal_sign",
      "type": "image",
      "subtype": "signature",
      "fieldKey": "signature",
      "label": "Principal Signature Image",
      "url": "data:image/png;base64,iVBORw0KGgo...",
      "x": 30, "y": 74, "width": 22, "height": 9,
      "zIndex": 5
    }
  ]
}

Element Types (type):

• field: Dynamic text populated from record[fieldKey]. Supports prefix (e.g. "Class : ") and suffix.
• label: Static text box displaying exact string inside text property.
• image: Photo, logo, or signature slot. If url is a Base64 string or remote image link, it renders directly; otherwise falls back to orgAssets or dynamic field data.
• shape: Solid colored boxes, headers, footer bands, or accent dividing strips (backgroundColor).
• barcode / qrcode: Automatically generates high-contrast SVG barcodes or QR codes encoding record[fieldKey].

5. Signature & Image Upload Guide (orgAssets & UI Uploads)

react-id-card-designer provides built-in support for uploading and managing organization assets such as school emblems, company logos, and authorized signatures:

1. Interactive File Uploads in Studio UI: Whenever a user selects any image element or Principal Signature box, the right-hand Property Inspector displays a dedicated Signature & Image Upload section. Users can click Upload Signature / Image File... (PNG/JPG) from their computer. The file is instantly converted to Base64 and stored inside the element's url property within the JSON schema.
2. Global Fallback Assets (orgAssets prop): You can provide default logos and signatures that apply whenever an element does not have a custom uploaded image:

   <IdCardDesignerModal
     orgAssets={{
       logoUrl: "https://myportal.com/assets/default_school_logo.png",
       signatureUrl: "https://myportal.com/assets/authorized_principal_sign.png",
       defaultAvatarUrl: "https://myportal.com/assets/default_student_avatar.png"
     }}
     // ...
   />

🚀 Real Data & Backend API Integration Guide

When integrating react-id-card-designer into your School ERP, HR Portal, or SaaS application, replacing dummy data with live backend records requires just three steps:

Step 1: Map Your Backend API Fields (fieldDefinitions)

Connect the exact property names returned by your backend API (REST, GraphQL, or SQL) to friendly UI labels using the fieldDefinitions prop. This tells the inspector dropdown what fields exist in your database.

// Example: If your backend returns [{ student_id: 104, full_name: "John Doe", class_section: "10-A", profile_url: "..." }]
const mySchoolFields = [
  { key: "full_name", label: "Student Full Name", defaultValue: "John Doe" },
  { key: "class_section", label: "Class & Section", defaultValue: "10-A" },
  { key: "student_id", label: "Admission / ID Number", defaultValue: "ADM-2026-104" },
  { key: "guardian_name", label: "Parent / Guardian Name", defaultValue: "Mr. Robert Doe" },
  { key: "dob", label: "Date of Birth", defaultValue: "15-08-2012" },
  { key: "phone_number", label: "Contact Phone", defaultValue: "+91 9876543210" }
];

Step 2: Pass Live Database Records & Persist Template (onSaveTemplate)

Fetch your live records from your API and pass them to sampleData so administrators can preview real students while designing. When they click Save & Apply Template, save the JSON schema right to your database!

import React, { useState, useEffect } from "react";
import { IdCardDesignerModal, IdCardPreview } from "react-id-card-designer";

export function SchoolCardManager() {
  const [students, setStudents] = useState([]);
  const [savedTemplate, setSavedTemplate] = useState(null);
  const [showDesigner, setShowDesigner] = useState(false);

  // 1. Fetch live student records & saved card template from your backend API
  useEffect(() => {
    async function loadBackendData() {
      const studentsRes = await fetch("/api/schools/1/students?class=10-A");
      const studentsData = await studentsRes.json();
      setStudents(studentsData);

      const templateRes = await fetch("/api/schools/1/card-template");
      const templateData = await templateRes.json();
      setSavedTemplate(templateData);
    }
    loadBackendData();
  }, []);

  // 2. Save modified template JSON directly back to your SQL/MongoDB database
  const handleSaveToDatabase = async (newTemplateSchema) => {
    setSavedTemplate(newTemplateSchema);
    setShowDesigner(false);

    await fetch("/api/schools/1/card-template", {
      method: "PUT",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(newTemplateSchema)
    });
    alert("Template saved successfully to database!");
  };

  return (
    <div>
      <button onClick={() => setShowDesigner(true)}>Customize Card Template</button>

      {/* Live Preview using the first student record from database */}
      {savedTemplate && students.length > 0 && (
        <IdCardPreview
          templateSchema={savedTemplate}
          data={students[0]} // Maps students[0].full_name, students[0].class_section automatically!
          orientation={savedTemplate.orientation}
          fieldDefinitions={mySchoolFields}
        />
      )}

      {/* Designer Studio Modal connected to live data */}
      <IdCardDesignerModal
        show={showDesigner}
        onHide={() => setShowDesigner(false)}
        theme="enterprise" // Or "dark"
        initialTemplate={savedTemplate}
        fieldDefinitions={mySchoolFields}
        sampleData={students} // Lets admin switch between live students in the top preview dropdown!
        orgAssets={{
          logoUrl: "https://myschoolapi.com/uploads/school_emblem.png",
          signatureUrl: "https://myschoolapi.com/uploads/principal_sign.png"
        }}
        onSaveTemplate={handleSaveToDatabase}
      />
    </div>
  );
}

Step 3: Batch Export Live Records to A4 Print Sheets

To generate multi-page A4 print sheets containing hundreds of live student records:

import { generateIdCardsPdf } from "react-id-card-designer";

async function exportBatchPrintSheets() {
  // 1. Fetch all students for the selected batch/class
  const response = await fetch("/api/schools/1/students?batch=2026");
  const liveStudents = await response.json();

  // 2. Fetch active template from database
  const templateRes = await fetch("/api/schools/1/card-template");
  const activeTemplate = await templateRes.json();

  // 3. Generate and download multi-page A4 PDF exactly aligned for PVC cutting
  await generateIdCardsPdf({
    records: liveStudents,            // Live database array
    templateSchema: activeTemplate,   // JSON schema stored in DB
    orientation: activeTemplate.orientation || "vertical",
    fileName: `Student_ID_Cards_Batch_${new Date().toISOString().slice(0, 10)}.pdf`,
    pageOptions: {
      format: "a4",
      scale: 2,                       // High DPI print resolution
      marginMm: 12,
      spacingMm: 8
    }
  });
}

📜 License

MIT © Stratametriq