1.1.0 • Published 3d ago

@stratametriq/id-card-designer

Licence

MIT

Version

1.1.0

Deps

Size

2.0 MB

Vulns

Weekly

Summary Dependency Versions

@stratametriq/id-card-designer

A universal, dynamic, and highly customizable ID Card Designer, Turnkey Dashboard & A4 Multi-Page PDF Rendering Engine for React, Vue, Angular, and Vanilla JS.

Whether you are building an Educational ERP / Student Information System, Faculty & Staff Directory, Hospital / Medical Access Portal, Corporate Employee Directory, or Event Badge Generator, @stratametriq/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

Turnkey All-In-One Dashboard (<IdCardManager />): Drop in a complete, ready-to-use workspace containing department tabs, live vector stage, batch A4 print setup, and roster selection table.
Interactive Visual Studio Canvas: Drag-and-drop element positioning (react-draggable), real-time zoom controls (80% - 200%), grid snapping (1mm / 5mm), and Z-index layering.
Technical Precision Rulers & Grid Overlay: Toggleable millimeter measurement rulers (0mm - 86mm) and radial matrix grid overlays for exact PVC card alignment.
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/Director signatures, employee photos, or organization logos (PNG/JPG) directly from the property inspector with live base64 conversion.
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, Corporate Executive, and Medical Staff Pass.
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, and prefixes/suffixes.
High-Resolution Batch PDF Export Engine: Built-in multi-page A4 / Letter grid layout calculation with toggleable hardware guillotine cut marks, perimeter outlines, and registration headers (html2canvas + jspdf).

Installation

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

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

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

Multi-Framework & Vanilla JS Support (`Vue`, `Angular`, `Svelte`, `Next.js` & `HTML`)

While the visual UI components (<IdCardManager /> and <IdCardDesignerModal />) are built with React hooks and drag-and-drop vector canvas state (react-draggable), this npm package can be used across any frontend framework or vanilla JavaScript project:

1. Using in React & Next.js (`React 18 / Vite / Remix / Next.js`)

Simply import our components directly into your React JSX/TSX tree:

import { IdCardManager } from "@stratametriq/id-card-designer";

2. Using in Vue, Angular, Svelte, or Vanilla HTML (`Micro-Frontend Mounting`)

If your application is built with Vue.js, Angular, Svelte, or plain HTML/JS, you can easily mount the turnkey <IdCardManager /> dashboard into any DOM element using createRoot in just a few lines of code:

<!-- Inside index.html or your Vue/Angular/Svelte component template -->
<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';

  // Mount the visual ID Card Dashboard cleanly inside any HTML div
  const rootElement = document.getElementById('id-card-manager-root');
  const root = createRoot(rootElement);
  
  root.render(React.createElement(IdCardManager, {
    onBatchExportComplete: (category, records) => {
      console.log(`Exported ${records.length} cards in ${category}`);
    }
  }));
</script>

3. Framework-Agnostic Pure JS Batch Print Engine (`generateIdCardsPdf`)

The core multi-page A4 and US Letter PDF rendering engine (generateIdCardsPdf) is completely framework-agnostic! Whether you are writing pure TypeScript, Node/Express frontend scripts, Vue, or Angular, you can import and run generateIdCardsPdf() directly without mounting any React UI components:

import { generateIdCardsPdf } from "@stratametriq/id-card-designer";

// Works natively across Vue, Angular, Svelte, and Vanilla JS!
await generateIdCardsPdf({
  records: myDatabaseArray,
  templateSchema: myLoadedJsonSchema,
  orientation: "vertical",
  fileName: "Batch_Job_Output.pdf"
});

Public API & Turnkey Dashboard Reference

When developers install @stratametriq/id-card-designer via npm, they can choose between two usage modes:

Turnkey Dashboard Mode (<IdCardManager />): Drop in a single component to instantly display the complete multi-department dashboard (navigation tabs, live card stage, roster directory table, and batch PDF export engine).
Custom Building Blocks Mode (<IdCardDesignerModal /> + <IdCardPreview />): Import atomic components to embed only the popup studio or live card preview into custom-built interfaces.

1. `<IdCardManager />` (Turnkey All-in-One Dashboard & 4-Step Master Workflow)

The <IdCardManager /> is the complete, out-of-the-box management suite. We engineered a clean, full-width unified layout with zero redundant navigation tabs so operators and end-users get a sleek, ultra-fast 4-step workflow:

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

export function MyOrganizationPortal() {
  return (
    <IdCardManager
      onSaveCategoryTemplate={(categoryKey, newTemplate) => {
        console.log(`Saved template for ${categoryKey}:`, newTemplate);
      }}
      onBatchExportComplete={(categoryKey, exportedRecords) => {
        console.log(`Exported ${exportedRecords.length} cards for ${categoryKey}`);
      }}
    />
  );
}

The Clean 4-Step Master Workflow Architecture

When users open <IdCardManager />, they interact with a unified, professional full-width screen broken into four logical steps:

Workflow Step	Section Title & Purpose	Detailed Functionality & Mathematical Features
Step 1	Select Department / Organization Category	A clean 4-card header grid showing your configured organization categories (e.g., Student IDs, Faculty & Admin, Corporate HR, Hospital Portal). Each card displays the number of bound data fields (`{fieldDefinitions.length} fields`) and template layouts (`{templateCount} template`). Clicking any card instantly switches the active category, isolating state, templates, and roster tables cleanly.
Step 2	Live Stage Preview & Studio Launcher	A high-resolution vector canvas preview displaying the currently selected person's ID card in real-time. Includes: • Interactive Zoom Controls (`80% - 150%`) alongside instant reset buttons. • Toggleable Grid & Measurement Rulers (`0-80mm`) for visual precision inspection. • Launch Studio Canvas Button: Opens our popup drag-and-drop design studio modal where operators can add new text fields, upload background textures, bind database keys, and drag elements around with snap-to-grid accuracy.
Step 3	Batch A4 Print Engine (`⚡ Live Sheet Matrix`)	A commercial print-engine sidebar that calculates and exports production-ready multi-page grid sheets: • Live Sheet Matrix Calculation Box: Dynamically computes physical sheet mathematics in real-time right before your eyes! When you toggle Paper Sheet Size (`A4` vs `US Letter`), Orientation (`Portrait` vs `Landscape` Sheet), or Card Cut Size (`86×54mm Standard ID-1`, `90×50mm Business Card`, `100×70mm Event Badge`), the matrix immediately recalculates the exact column × row capacity (`e.g., 3 Cols × 3 Rows = 9 cards/page`) and total job pages required. • Hardware Cut Guides Checkboxes: Toggle corner crosshair cut marks (`0.35mm stroke`), card perimeter cut outline guides, and technical registration headers (`PRECISION CUT SHEET — JOB SPECIFICATIONS`) for print shop operators.
Step 4	Live Roster Directory Table	Displays a dynamic, paginated table of all people in that department. Columns automatically reflect your category's database fields (`studentName`, `admissionNo`, `classSec`, etc.). Check or uncheck individual records to include them in the Batch A4 Print Engine, or click any row to preview their rendered card live in Step 2!

Zero-Configuration Automatic Field Discovery (`Auto-Detecting User Database Columns`)

You never have to worry about missing fields. If your database or user records contain custom columns that are not explicitly defined in fieldDefinitions, <IdCardManager /> and our Studio Canvas (ElementPropertyEditor) handle them automatically:

Auto-Discovery Scan: When you open the Studio Canvas, our property engine scans Object.keys(sampleData[0]) directly from the live database records you passed in.
Auto-Formatting: Raw database keys like bloodGroup, busRouteNo, emergencyPhone, allergyAlert, or parkingSlot are automatically transformed into clean human-readable titles (e.g., "Bus Route No (busRouteNo)").
Instant Binding: Every discovered key is automatically merged into the Data Field Key dropdown in the right sidebar under 4. ELEMENT PROPERTIES. Any user can click + Add Element Dynamic Field, select their custom database key, and bind it immediately without writing a single line of code!

2. Customizing Categories & Dynamic Fields (`categories` & `sampleRecords` Props)

By default, <IdCardManager /> includes four global starter categories: Student ID Cards (Education), Faculty & Administration, Corporate Employee Badges, and Healthcare & Medical Pass.

You can pass your own custom categories and live database records directly via props without editing the library:

const myCustomCategories = {
  university: {
    id: "university",
    label: "University Engineering Students",
    badge: "🎓 Higher Education",
    themeColor: "#0d6efd",
    defaultOrientation: "vertical",
    templateCount: 2,
    description: "Dynamic field binding tailored for enrollment numbers, engineering departments, and library barcodes.",
    fieldDefinitions: [
      { key: "studentName", label: "Student Full Name", defaultValue: "Aarav Sharma" },
      { key: "enrollmentNo", label: "Enrollment Number", defaultValue: "ENR-2026-991" },
      { key: "branch", label: "Engineering Branch", defaultValue: "Computer Science & Engineering" },
      { key: "year", label: "Academic Year", defaultValue: "B.Tech Year 3" },
      { key: "bloodGroup", label: "Blood Group", defaultValue: 'O+ POSITIVE' }
    ]
  },
  executives: {
    id: "executives",
    label: "Global Executive Badges",
    badge: "🏢 Corporate HQ",
    themeColor: "#6f42c1",
    defaultOrientation: "horizontal",
    templateCount: 1,
    description: "Dynamic field binding tailored for corporate executive designations, floor security clearance, and access barcodes.",
    fieldDefinitions: [
      { key: "execName", label: "Executive Full Name", defaultValue: "Elena Rostova" },
      { key: "designation", label: "Designation / Role", defaultValue: "VP of Cloud Engineering" },
      { key: "empCode", label: "Employee ID Code", defaultValue: "EMP-HQ-402" },
      { key: "clearance", label: "Security Clearance", defaultValue: "Level 5 (All Floors & Server Rooms)" }
    ]
  }
};

const myLiveRecords = {
  university: [
    { studentName: "Aarav Sharma", enrollmentNo: "ENR-2026-991", branch: "Computer Science", year: "B.Tech Year 3", bloodGroup: "O+ POSITIVE" },
    { studentName: "Diya Patel", enrollmentNo: "ENR-2026-992", branch: "Electronics & Comm", year: "B.Tech Year 2", bloodGroup: "B+ POSITIVE" }
  ],
  executives: [
    { execName: "Elena Rostova", designation: "VP of Cloud Engineering", empCode: "EMP-HQ-402", clearance: "Level 5" }
  ]
};

export function CustomApp() {
  return (
    <IdCardManager
      categories={myCustomCategories}
      sampleRecords={myLiveRecords}
    />
  );
}

The standalone interactive modal component for designing and modifying ID card templates. Use this when embedding only the popup studio inside your own custom interface without the turnkey dashboard.

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.

4. `<IdCardPreview />` (Atomic Card Renderer)

A lightweight component for rendering a single high-resolution vector 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.

5. `generateIdCardsPdf(options)` (Programmatic Batch Print Utility)

An asynchronous utility function to generate multi-page, high-resolution A4 or Letter PDFs for batch printing from anywhere in your application.

import { generateIdCardsPdf } from "@stratametriq/id-card-designer";

await generateIdCardsPdf({
  records: [...],             // Array of data records to render
  templateSchema: {...},      // JSON template schema object
  orientation: "vertical",    // "vertical" | "horizontal"
  fileName: "ID_Cards_Sheet.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
    showCropMarks: true,      // Add corner crosshair cut guides
    showCutOutline: true,     // Add faint card perimeter borders
    showHeader: true          // Add technical registration header
  },
  onProgress: (current, total) => {
    console.log(`Rendered page ${current} of ${total}`);
  }
});

6. JSON Template Schema Structure (`templateSchema`)

Every design created in <IdCardDesignerModal /> is stored and exported as a clean, serializable JSON schema:

{
  "id": "tpl_school_vertical_01",
  "name": "Classic Vertical ID",
  "orientation": "vertical",
  "width": 54,
  "height": 86,
  "background": {
    "color": "#ffffff",
    "image": "https://myportal.com/assets/card-bg-watermark.png",
    "size": "cover"
  },
  "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
    }
  ]
}

Multi-Department Architecture (The Dictionary Pattern)

If your software serves multiple organizational departments (e.g., Students vs. Teachers vs. Hospital Doctors vs. Corporate HR), you do not need multiple modal components or hardcoded libraries. Instead, use the Dictionary Pattern to silo category schemas while sharing a single universal <IdCardDesignerModal /> or <IdCardManager /> instance:

const CATEGORY_CONFIGS = {
  student: {
    title: "Student ID Cards",
    defaultOrientation: "vertical",
    fieldDefinitions: [
      { key: "studentName", label: "Student Full Name", defaultValue: "Aarav Sharma" },
      { key: "admissionNo", label: "Admission Number", defaultValue: "ADM-2026-089" },
      { key: "classSec", label: "Class & Section", defaultValue: "Grade 10 [A]" }
    ]
  },
  staff: {
    title: "Faculty & Staff Directory",
    defaultOrientation: "horizontal",
    fieldDefinitions: [
      { key: "facultyName", label: "Faculty / Staff Name", defaultValue: "Dr. Ananya Iyer" },
      { key: "empCode", label: "Employee ID Code", defaultValue: "EMP-FAC-104" },
      { key: "designation", label: "Job Designation", defaultValue: "Senior Physics Lecturer" }
    ]
  }
};

License

MIT Stratametriq

Keywords

react id-card designer badge-generator pdf html2canvas jspdf drag-and-drop canvas a4-export