product-customizer
v1.0.4
Published
Product customization library
Readme
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-customizerCDN
<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:allTesting
# Run type checking
npm run type-check
# Watch mode
npm run type-check:watchContributing
- 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