Hakama.js Documentation

Overview

Hakama.js is a lightweight, ES5-compatible JavaScript library that adds virtual try-on functionality to your e-commerce site. It automatically injects action buttons into product cards, opens a modal for image upload, and optionally integrates with your Try-On API to generate virtual try-on previews.

Key Features

Image Management

• Upload exactly ONE user image (jpeg/jpg/png/webp)
• Automatic file type and size validation
• Persist in IndexedDB (best practice) with base64 fallback
• Auto-load previously saved image whenever the modal opens
• Remove/Clear saved photo and allow re-upload

Modal Experience

• Full-page overlay with customizable styling
• Side-by-side thumbnail preview (clothing + user photo)
• Full-width result display area
• Close on Escape key or backdrop click
• Scroll lock when modal is open

Try-On Integration

• POST multipart/form-data with { person, clothing } images
• Automatic preparation of image blobs
• Cloudflare Turnstile token injection
• Custom API headers support
• Error handling and retry logic

Developer Experience

• ES5-compatible (works in older browsers)
• No dependencies required
• Automatic DOM observation for dynamic content
• Custom button templates
• Comprehensive event callbacks
• TypeScript-friendly API

Installation

CDN (Recommended for Quick Setup)

<script src="https://hakama.io/hakama.min.js"></script>

Quick Start

Basic Setup

The simplest way to get started:

                            
<!-- Your product cards -->
<div class="card">
    <img src="product1.jpg" alt="Product 1">
    <h3>Blue Jacket</h3>
    <div class="actions"></div>
</div>

<!-- Include Hakama -->
<script src="https://hakama.io/hakama.min.js"></script>
<script>
Hakama.init({
    cardSelector: '.card',
    insertIntoSelector: '.actions',
    buttonText: 'Try On',
    buttonClass: 'btn btn-primary',
    key: 'your-api-key',
});
</script>

                        

With Auto-Initialization

Define configuration before loading the script:

<script>
window.HakamaConfig = {
    cardSelector: '.card',
    buttonText: 'Try On',
    tryOnEnabled: true,
    tryOnEndpoint: '/api/try-on'
};
</script>
<script src="hakama.js"></script>
                            

Configuration Options

Hakama.js provides extensive configuration options to customize behavior, appearance, and integration with your Try-On API.

Card & Button Configuration

Control how buttons are injected into your product cards:

Hakama.init({
    buttonTemplate: function(opts, card) {
    var btn = document.createElement('button');
    btn.className = 'custom-tryon-btn';
    btn.innerHTML = '<span>👔</span> Try It On';
        return btn;
    }
});

Filter Options

DOM Observation

Click Behavior

Modal Configuration

Customize the modal appearance and behavior:

Upload Configuration

Control image upload behavior:

Remove/Clear Configuration

Storage Configuration

Configure where and how user images are stored:

Try-On API Configuration

Configure integration with your virtual try-on API:

Styling Configuration

Control CSS injection and styling:

API Reference

Storage System

How It Works

Hakama uses a dual-storage strategy to ensure user photos persist reliably across sessions:

Usage Examples

Basic Implementation

<script src="hakama.js"></script>
<script>
Hakama.init({
    cardSelector: '.card',
    buttonText: 'Try On',
    buttonClass: 'btn btn-primary'
});
</script>

E-commerce Integration

Hakama.init({
    cardSelector: '.product-card',
    buttonText: '👔 Virtual Try-On',
    tryOnEnabled: true,
    tryOnEndpoint: '/api/virtual-tryon',
    key: 'api-key',
    maxFileSizeBytes: 10 * 1024 * 1024,

    onTryOnResult: function(card, resultUrl) {
        gtag('event', 'tryon_success');
    }
});