Product-customizer NPM

Product Customizer Library

A lightweight, customizable TypeScript library for adding product customization features to e-commerce websites. This library allows customers to add text and images to specific areas of products, perfect for personalized merchandise.

Features

🎨 Canvas-based customization
📱 Responsive design with touch support
🖼️ Support for both text and image customizations
🎯 Multiple customizable areas per product
🌓 Light and dark theme support
💾 Customization history tracking
📐 Auto-scaling and positioning
🔄 Real-time preview updates
🔧 Canvas and Form Separation for custom layouts

Installation

NPM

npm install product-customizer

CDN

<script
  src="https://unpkg.com/product-customizer/dist/product-customizer.min.js"
  defer="defer"
></script>

or

<script
  src="https://cdn.jsdelivr.net/npm/product-customizer/dist/product-customizer.min.js"
  defer="defer"
></script>

Quick Start

import { ProductCustomizer } from "product-customizer";

// Initialize the customizer
const customizer = new ProductCustomizer({
  canvasContainerId: "canvas-container",
  formContainerId: "form-container",
});

// Add a product
const product = customizer.addProduct({
  id: "tshirt-001",
  name: "Custom T-Shirt",
  imageUrl: "/images/tshirt.jpg",
  price: 29.99,
  customizationPrice: 5.0,
});

// Add customizable areas
product.addCustomizableArea("front-chest", {
  x: 150,
  y: 150,
  width: 200,
  height: 150,
  type: "both", // 'text', 'image', or 'both'
  label: "Front Design",
});

// Set active product
customizer.setActiveProduct("tshirt-001");

Configuration

Customizer Options

interface CustomizerOptions {
  canvasContainerId?: string; // ID of the element where the canvas will be rendered
  formContainerId?: string; // ID of the element where the form will be rendered
  width?: string; // Default: '300px'
  height?: string; // Default: '100%'
  position?: "left" | "right"; // Default: 'right'
  theme?: "light" | "dark"; // Default: 'light'
}

Area Configuration

interface AreaConfig {
  x: number; // X coordinate
  y: number; // Y coordinate
  width: number; // Area width
  height: number; // Area height
  type?: "text" | "image" | "both"; // Default: 'text'
  label?: string; // Area label
}

API Reference

ProductCustomizer Class

Methods

Method	Description
`constructor(options?: CustomizerOptions)`	Initialize a new customizer instance
`addProduct(config: ProductConfig)`	Add a new product
`setActiveProduct(productId: string)`	Set the active product
`destroy()`	Clean up and remove the customizer

Product Class

Methods

Method	Description
`addCustomizableArea(id: string, config: AreaConfig)`	Add a customizable area
`get().area`	Get a specific area
`get().allAreas`	Get all areas
`get().totalPrice`	Get total price including customizations

Complete Example

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Product Customizer Demo</title>
    <script src="product-customizer.min.js"></script>
    <style>
      #canvas-container {
        width: 600px;
        height: 400px;
        border: 1px solid #ccc;
        margin-bottom: 20px;
      }

      #form-container {
        padding: 10px;
        border: 1px solid #ccc;
      }
    </style>
  </head>
  <body>
    <div id="app">
      <h1>Product Customizer Demo</h1>
      <div id="canvas-container"></div>
      <div id="form-container"></div>
      <button onclick="toggleCustomizer()">Customize Product</button>
    </div>

    <script>
      // Initialize customizer
      const customizer = new ProductCustomizer({
        canvasContainerId: "canvas-container",
        formContainerId: "form-container",
        theme: "light",
      });

      // Add product
      const product = customizer.addProduct({
        id: "tshirt-001",
        name: "Classic T-Shirt",
        imageUrl: "/images/tshirt.jpg",
        price: 29.99,
        customizationPrice: 5.0,
      });

      // Add customizable areas
      product.addCustomizableArea("front", {
        x: 150,
        y: 150,
        width: 200,
        height: 150,
        type: "both",
        label: "Front Design",
      });

      // Set as active product
      customizer.setActiveProduct("tshirt-001");

      // Toggle customizer visibility
      function toggleCustomizer() {
        customizer.toggle();
      }

      // Display customizations
      function showCustomizations() {
        const customizations = JSON.parse(
          document.getElementById("product-customizations")?.value || "[]"
        );
        console.log("Current customizations:", customizations);
      }
    </script>
  </body>
</html>

Getting Customization Data

The library stores customization data in a hidden input field with the ID product-customizations. You can access this data as follows:

const customizations = JSON.parse(
  document.getElementById("product-customizations")?.value || "[]"
);

The customization data structure looks like this:

interface CustomizationHistoryItem {
  productId: string;
  areaId: string;
  type: "text" | "image" | "both";
  text?: string;
  image?: File;
  timestamp: string;
}

Best Practices

Cleanup: Always call destroy() when removing the customizer

window.addEventListener("beforeunload", () => {
  customizer.destroy();
});

Error Handling: Add error handling for image loading

const img = new Image();
img.onerror = () => console.error("Failed to load image");
img.src = "path/to/image.jpg";

Responsive Design: The customizer automatically handles window resizing, but you might want to adjust the container size:

window.addEventListener("resize", () => {
  if (window.innerWidth < 768) {
    customizer.hide();
  }
});

Browser Support

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)
IE11 (with polyfills)

Development

Setup

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build:all

Testing

# Run type checking
npm run type-check

# Watch mode
npm run type-check:watch

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

License

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

Acknowledgments

Thanks to all contributors
Inspired by various product customization tools
Built with TypeScript and modern web technologies

customizer product canvas

8 months ago

8 months ago

8 months ago

8 months ago

8 years ago