@shimmerbyte/drag-cart

A highly configurable, TypeScript-first drag-and-drop shopping cart system for React applications. Provides smooth animations, customizable theming, and minimal dependencies.

✨ Features

• 🎯 Zero Dependencies - Only React and React-DOM as peer dependencies
• 🎨 Fully Customizable - Complete theming and styling control
• 📱 Touch Friendly - Works on mobile and desktop
• 🔧 TypeScript Native - Full type safety with generics
• 🚀 Performance Optimized - Minimal re-renders and efficient animations
• 💾 Persistence Built-in - localStorage/sessionStorage support (Pro+)
• 🎭 Render Props - Custom render functions for complete control (Pro+)
• 🧩 Modular Design - Use individual hooks and components as needed
• 📊 Analytics Ready - Built-in tracking for cart interactions (Pro+)
• 🆓 Freemium Model - Start free, upgrade when you need more

💰 Pricing

Free Tier

• ✅ Up to 5 items per cart
• ✅ Basic drag & drop functionality
• ✅ Standard animations
• ✅ Community support
• ⚠️ Includes watermark

Pro Tier - $29/month

• ✅ Up to 100 items per cart
• ✅ Multiple carts (up to 5)
• ✅ Custom themes & advanced animations
• ✅ Cart persistence
• ✅ Analytics tracking
• ✅ Custom render functions
• ✅ No watermark
• ✅ Priority support

Enterprise Tier - $99/month

• ✅ Unlimited items & carts
• ✅ White-label licensing
• ✅ Advanced customization
• ✅ Dedicated support
• ✅ Custom integrations

Get your license key →

📦 Installation

npm install @shimmerbyte/drag-cart
# or
yarn add @shimmerbyte/drag-cart

🚀 Quick Start

Basic Setup (Free Tier)

import React from 'react';
import { 
  CartProvider, 
  DragCart, 
  useDragHandlers, 
  useCartMethods 
} from '@shimmerbyte/drag-cart';

// Your product type
interface Product {
  id: string;
  title: string;
  price: number;
  image?: string;
}

// Draggable product component
const ProductCard: React.FC<{ product: Product }> = ({ product }) => {
  const dragHandlers = useDragHandlers<Product>();
  
  return (
    <div className="product-card">
      <h3>{product.title}</h3>
      <p>${product.price}</p>
      
      {/* Drag handle */}
      <button
        onMouseDown={(e) => dragHandlers.onMouseDown(e, {
          id: product.id,
          data: product
        })}
        className="drag-handle"
      >
        🛒 Drag to Cart
      </button>
    </div>
  );
};

// Cart display component
const CartDisplay: React.FC = () => {
  const { items, itemCount, removeItem } = useCartMethods<Product>();
  
  return (
    <div className="cart">
      <h3>Cart ({itemCount} items)</h3>
      {items.map(item => (
        <div key={item.id} className="cart-item">
          <span>{item.data.title}</span>
          <span>${item.data.price}</span>
          <button onClick={() => removeItem(item.id)}>Remove</button>
        </div>
      ))}
    </div>
  );
};

// Main app
const App: React.FC = () => {
  const products: Product[] = [
    { id: '1', title: 'Awesome Product', price: 29.99 },
    { id: '2', title: 'Cool Gadget', price: 49.99 },
  ];

  return (
    <CartProvider<Product>>
      <div className="app">
        <div className="products">
          {products.map(product => (
            <ProductCard key={product.id} product={product} />
          ))}
        </div>
        
        <CartDisplay />
        
        {/* Drag and drop system */}
        <DragCart<Product> 
          onDrop={(item) => console.log('Added to cart:', item.data.title)}
        />
      </div>
    </CartProvider>
  );
};

Pro Setup with License Key

import { CartProvider } from '@shimmerbyte/drag-cart';

const proConfig = {
  license: {
    tier: 'pro' as const,
    apiKey: 'your-pro-license-key-here',
  },
  maxItems: 100,
  persistence: {
    key: 'my-app-cart',
    storage: 'localStorage',
  },
  analytics: {
    enabled: true,
    trackingId: 'your-analytics-id',
  },
};

<CartProvider<Product> config={proConfig}>
  {/* Your app */}
</CartProvider>

🔑 License Management

Getting Your License Key

1. Visit shimmerbyte.com/drag-cart/pricing
2. Choose your plan (Pro or Enterprise)
3. Complete the checkout process
4. You'll receive your license key via email
5. Add it to your configuration

License Configuration

import { LicenseConfig } from '@shimmerbyte/drag-cart';

const licenseConfig: LicenseConfig = {
  tier: 'pro', // 'free' | 'pro' | 'enterprise'
  apiKey: 'pk_live_your_license_key_here',
  // Optional: Set expiration for trial licenses
  expiresAt: '2024-12-31T23:59:59Z',
};

Environment Variables

For security, store your license key in environment variables:

# .env
REACT_APP_DRAG_CART_LICENSE_KEY=pk_live_your_license_key_here

const config = {
  license: {
    tier: 'pro' as const,
    apiKey: process.env.REACT_APP_DRAG_CART_LICENSE_KEY,
  },
};

License Validation

The library automatically validates your license:

import { useLicense } from '@shimmerbyte/drag-cart';

const MyComponent = () => {
  const { isValid, error, canUseFeature, upgradeUrl } = useLicense();
  
  if (!isValid) {
    return (
      <div>
        <p>License error: {error}</p>
        <a href={upgradeUrl}>Upgrade Now</a>
      </div>
    );
  }
  
  return (
    <div>
      {canUseFeature('customThemes') && <CustomThemeSelector />}
      {canUseFeature('analytics') && <AnalyticsDashboard />}
    </div>
  );
};

🎨 Theming & Customization

Basic Theming (All Tiers)

const basicTheme = {
  colors: {
    primary: '#your-brand-color',
    secondary: '#your-secondary-color',
  },
};

<CartProvider theme={basicTheme}>
  {/* Your app */}
</CartProvider>

Advanced Theming (Pro+ Only)

const advancedTheme = {
  overlay: {
    background: 'rgba(255, 255, 255, 0.95)',
    border: '3px solid #ff6b6b',
    borderRadius: '12px',
    shadow: '0 20px 40px rgba(255, 107, 107, 0.3)',
  },
  animations: {
    duration: '400ms',
    easing: 'cubic-bezier(0.68, -0.55, 0.265, 1.55)',
  },
};

Custom Render Functions (Pro+ Only)

const CustomDragCart: React.FC = () => {
  return (
    <DragCart<Product>
      renderOverlay={(item, isOverDropZone) => (
        <div className={`custom-overlay ${isOverDropZone ? 'active' : ''}`}>
          <img src={item.data.image} alt={item.data.title} />
          <h4>{item.data.title}</h4>
          <p>${item.data.price}</p>
          {isOverDropZone && <span>✅ Ready to add!</span>}
        </div>
      )}
      renderDropZone={(isActive) => (
        <div className={`custom-drop-zone ${isActive ? 'active' : ''}`}>
          {isActive ? '🎯 Drop it!' : '🛒 Cart'}
        </div>
      )}
    />
  );
};

📊 Analytics (Pro+ Only)

const analyticsConfig = {
  analytics: {
    enabled: true,
    trackingId: 'your-analytics-id',
    events: {
      dragStart: true,
      dragEnd: true,
      itemAdded: true,
      itemRemoved: true,
      cartCleared: true,
    },
  },
};

🔧 Advanced Configuration

Feature Limits by Tier

| Feature | Free | Pro | Enterprise | |---------|------|-----|------------| | Max Items | 5 | 100 | Unlimited | | Max Carts | 1 | 5 | Unlimited | | Custom Themes | ❌ | ✅ | ✅ | | Advanced Animations | ❌ | ✅ | ✅ | | Persistence | ❌ | ✅ | ✅ | | Analytics | ❌ | ✅ | ✅ | | Custom Render | ❌ | ✅ | ✅ | | Watermark | ✅ | ❌ | ❌ |

Upgrade Prompts

The library automatically shows upgrade prompts when users hit limits:

// Customize upgrade prompts
const config = {
  onLicenseError: (error: string) => {
    console.log('License error:', error);
    // Show custom upgrade UI
  },
};

🐛 Troubleshooting

License Issues

1. Invalid License Key

   • Verify your license key is correct
   • Check if it's expired
   • Ensure you're using the right tier

2. Network Issues

   • License validation requires internet connection
   • Check firewall/proxy settings
   • Validation is cached for 1 hour

3. Development Mode

   • Use test keys: test_pro_key or test_enterprise_key
   • Set NODE_ENV=development

Common Issues

1. Watermark Showing on Paid Tier

   • Check license validation
   • Verify API key is correct
   • Clear license cache: licenseValidator.clearCache()

2. Features Not Working

   • Check tier limits with useLicense().limits
   • Verify license is valid with useLicense().isValid

🤝 Support

• Free Tier: Community support via GitHub Issues
• Pro Tier: Priority email support (24-48h response)
• Enterprise Tier: Dedicated support with SLA

📄 License

MIT License - see LICENSE file for details.

Note: While the code is MIT licensed, commercial usage beyond the free tier limits requires a valid license key from SHiMMeRbyte.

Built with ❤️ by the SHiMMeRbyte team

Get your license key • Documentation • Support