@cshah18/creative-builder

A powerful React creative builder component for designing interactive ads, templates, and creative content with drag-and-drop functionality, animations, WebGL support, and comprehensive tracking.

🚀 Features

• 🎨 Complete Playground - Full-featured creative builder with drag & drop
• 📱 Responsive Design - Works seamlessly on desktop, tablet, and mobile
• 🎬 Rich Animations - Entrance, exit, and interaction animations
• 🎮 WebGL Support - 3D graphics and interactive content
• 📊 Analytics Ready - Built-in impression and click tracking
• 🎯 100+ Templates - Pre-designed templates across 25+ categories
• 📐 Multiple Artboard Sizes - Standard ad sizes, social media formats
• 💾 Export Options - HTML5 output with embedded tracking
• 🔧 Programmatic Control - Full API access via refs
• 🎁 External Functions - Use builder features outside the component

📦 Installation

npm install @cshah18/creative-builder

Peer Dependencies

npm install react react-dom lucide-react sonner

🎯 Quick Start

Basic Usage - Complete Playground

import { CreativeBuilderPlayground } from '@cshah18/creative-builder';
import '@cshah18/creative-builder/styles';

function App() {
  return (
    <div className="h-screen">
      <CreativeBuilderPlayground />
    </div>
  );
}

📚 API Reference

CreativeBuilderPlayground Component

The main component that provides a complete creative builder experience.

Props

interface CreativeBuilderPlaygroundProps {
  initialCreative?: Creative;
  onCreativeChange?: (creative: Creative) => void;
  onExport?: (creative: Creative, html: string) => void;
  onPreview?: (creative: Creative, html: string) => void;
  onSave?: (creative: Creative) => void;
  customTemplates?: CreativeTemplate[];
  productUrl?: string;  // Default product URL to inject into templates
  logoUrl?: string;     // Default logo URL to inject into templates
  hidePanels?: {
    componentLibrary?: boolean;
    propertyPanel?: boolean;
    toolbar?: boolean;
    animationTimeline?: boolean;
  };
  className?: string;
}

Ref Methods

interface CreativeBuilderPlaygroundRef {
  getCreative: () => Creative;
  setCreative: (creative: Creative) => void;
  getHTML: () => string;
  preview: () => void;
  export: (fileName?: string) => void;
  clear: () => void;
  loadTemplate: (template: CreativeTemplate) => void;
}

💡 Usage Examples

1. With Event Handlers

import { CreativeBuilderPlayground } from '@cshah18/creative-builder';

function App() {
  return (
    <CreativeBuilderPlayground
      onCreativeChange={(creative) => console.log('Updated:', creative)}
      onExport={(creative, html) => console.log('Exported:', html)}
      onSave={(creative) => {
        fetch('/api/creatives', {
          method: 'POST',
          body: JSON.stringify(creative)
        });
      }}
    />
  );
}

2. With Default Product URL and Logo URL

Set default images that will be injected into all HTML templates:

import { CreativeBuilderPlayground } from '@cshah18/creative-builder';

function App() {
  const productUrl = 'https://example.com/product-image.jpg';
  const logoUrl = 'https://example.com/logo.png';
  
  return (
    <CreativeBuilderPlayground
      productUrl={productUrl}
      logoUrl={logoUrl}
      onCreativeChange={(creative) => console.log('Updated:', creative)}
    />
  );
}

This will automatically replace:

• The src attribute of any <img> tag with id="editable-product-image" with productUrl
• The src attribute of any <img> tag with id="editable-logo" with logoUrl

When users switch between templates, the default images are maintained.

3. With Ref for Programmatic Control

import { useRef } from 'react';
import { 
  CreativeBuilderPlayground, 
  CreativeBuilderPlaygroundRef 
} from '@cshah18/creative-builder';

function App() {
  const ref = useRef<CreativeBuilderPlaygroundRef>(null);

  return (
    <>
      <button onClick={() => ref.current?.getHTML()}>Get HTML</button>
      <button onClick={() => ref.current?.preview()}>Preview</button>
      <CreativeBuilderPlayground ref={ref} />
    </>
  );
}

4. Using External Utility Functions

import { 
  getCreativeHTML,
  previewCreative,
  exportCreativeAsHTML,
  injectProductUrl,
  injectLogoUrl
} from '@cshah18/creative-builder';

// Get HTML from creative object
const html = getCreativeHTML(creative);

// Preview in new window
previewCreative(creative);

// Export as file
exportCreativeAsHTML(creative, 'my-ad.html');

// Inject product URL into HTML
const modifiedHtml = injectProductUrl(htmlContent, 'https://example.com/image.jpg');

// Inject logo URL into HTML
const htmlWithLogo = injectLogoUrl(htmlContent, 'https://example.com/logo.png');

📝 Example Project

Check out the complete example app in the example/ directory:

cd example
npm install
npm run dev

The example demonstrates:

• ✅ Complete playground integration
• ✅ Programmatic control via refs
• ✅ External utility functions
• ✅ Custom event handlers
• ✅ Loading custom creatives
• ✅ Getting HTML output

🎓 Element Types

• Text: Customizable text with font, color, size
• Image: Images with click URLs and border radius
• Button: Interactive buttons with tracking
• Countdown: Dynamic countdown timers
• Progress Bar: Visual progress with API integration
• API Data: Dynamic content from external APIs
• WebGL: 3D graphics and scenes
• Canvas: Custom animations
• Video: Embedded videos
• Audio: Audio players
• HTML: Custom HTML content

📐 Artboard Sizes

Pre-configured sizes available via ARTBOARD_SIZES:

• Banner Ads (728x90, 300x250, 160x600)
• Mobile (320x100, 320x480)
• Social Media (Instagram, Facebook, Twitter)
• Video (1920x1080)
• Custom dimensions

🎨 Templates

100+ templates across 25+ categories accessible via TEMPLATES.

🛠️ Development

# Install dependencies
npm install

# Run dev server
npm run dev

# Build library
npm run build:lib

# Run example
cd example && npm run dev

📄 License

MIT

🤝 Contributing

Contributions welcome! Please submit a Pull Request.

📧 Support

• GitHub: https://github.com/CShah18/drop-spark-lab/issues
• Email: [email protected]

Made with ❤️ by CoBuy

What technologies are used for this project?

This project is built with:

• Vite
• TypeScript
• React
• shadcn-ui
• Tailwind CSS

How can I deploy this project?

Simply open Lovable and click on Share -> Publish.

Can I connect a custom domain to my Lovable project?

Yes, you can!

To connect a domain, navigate to Project > Settings > Domains and click Connect Domain.

Read more here: Setting up a custom domain

Responsive Embedding Guidance

When embedding CreativeBuilder inside another application layout (e.g., a dashboard panel or modal), avoid forcing h-screen unless you truly want full viewport editing.

1. Use a flexible parent such as <div className="flex-grow min-h-[500px]"> or a grid cell.
2. Leave fillViewport at its default (false) so the builder adapts to the parent height.
3. Set fillViewport only when you want immersive full-height editing.
4. The toolbar wraps on narrow widths; ensure parent containers do not clip its second row with overflow:hidden.
5. Side panels shrink responsively; below the lg breakpoint the Component Library becomes an overlay via the floating action button.

Example embedded usage:

<section className="grid grid-cols-1 lg:grid-cols-2 gap-6">
  <div className="rounded-lg border p-4">
    <h3 className="font-semibold mb-2">Editor</h3>
    <CreativeBuilder className="rounded-md" />
  </div>
  <div className="rounded-lg border p-4">
    <h3 className="font-semibold mb-2">Preview Pane</h3>
    {/* Your preview / analytics */}
  </div>
</section>