@obundu/cart-system

Complete e-commerce cart system with product variants, gallery, and localStorage persistence for Webflow and custom websites.

📦 Installation

npm install @obundu/cart-system

Or use via CDN:

<!-- All-in-one bundle -->
<script src="https://unpkg.com/@obundu/cart-system@latest/dist/obundu-cart.min.js"></script>

<!-- Or individual modules -->
<script src="https://unpkg.com/@obundu/cart-system@latest/dist/cart-system.min.js"></script>
<script src="https://unpkg.com/@obundu/cart-system@latest/dist/cart-page.min.js"></script>
<script src="https://unpkg.com/@obundu/cart-system@latest/dist/product-variants.min.js"></script>
<script src="https://unpkg.com/@obundu/cart-system@latest/dist/product-gallery.min.js"></script>

🚀 Quick Start

1. Include the Scripts

<!-- Add before closing </body> tag -->
<script src="path/to/cart-system.js"></script>
<script src="path/to/product-variants.js"></script>
<script src="path/to/product-gallery.js"></script>

2. Add HTML Attributes

<!-- Product Container -->
<div ob-cart-item-id="prod-001" 
     ob-cart-item-name="Contemporary Kimono Jacket"
     ob-cart-item-price="450"
     ob-cart-item-image="https://...">
  
  <!-- Add to Cart Button -->
  <button ob-cart-add>Add to Cart</button>
  
  <!-- Cart Icon with Badge -->
  <a href="#" ob-cart-open>
    <svg>...</svg>
    <span ob-cart-count>0</span>
  </a>
</div>

3. Add Cart Popup

<!-- Cart Popup -->
<div class="cart-popup" ob-cart-popup>
  <div class="cart-overlay" ob-cart-overlay></div>
  <div class="cart-panel">
    <button ob-cart-close>×</button>
    <div ob-cart-list></div>
    <div ob-cart-total>$0</div>
  </div>
</div>

📚 Modules

🛒 Cart System (cart-system.js)

Main cart management with localStorage persistence.

Features:

• Add/remove items
• Update quantities
• Variant support (color, size)
• Cart popup management
• localStorage persistence

Attributes:

• ob-cart-item-id - Product container
• ob-cart-item-name - Product name
• ob-cart-item-price - Product price
• ob-cart-item-image - Product image URL
• ob-cart-add - Add to cart button
• ob-cart-open - Open cart popup
• ob-cart-close - Close cart popup
• ob-cart-list - Cart items container
• ob-cart-total - Total price display
• ob-cart-count - Cart count badge

📄 Cart Page (cart-page.js)

Full-page cart display and management.

Features:

• Display all cart items
• Update quantities
• Remove items
• Calculate totals
• Empty state handling

Attributes:

• ob-cart-page-list - Cart items container
• ob-cart-page-total - Total price display
• ob-cart-page-qty-plus - Increase quantity
• ob-cart-page-qty-minus - Decrease quantity
• ob-cart-page-remove - Remove item

🎨 Product Variants (product-variants.js)

Handle color and size selection.

Features:

• Color selection
• Size selection
• Visual state management
• Integration with cart system

Attributes:

• ob-product-color - Color option
• ob-product-size - Size option

🖼️ Product Gallery (product-gallery.js)

Interactive product image gallery.

Features:

• Click thumbnails to change main image
• Smooth transitions
• Active state indicators
• Hover effects

Classes:

• .product_thumbnail - Main product image
• .product_gallery_image - Thumbnail images

🎯 Usage Examples

Basic Product Page

<div ob-cart-item-id="prod-001" 
     ob-cart-item-name="Kimono Jacket"
     ob-cart-item-price="450"
     ob-cart-item-image="https://example.com/image.jpg">
  
  <!-- Color Selection -->
  <div ob-product-color="Black">
    <input type="radio" name="color" value="Black" checked>
    Black
  </div>
  <div ob-product-color="White">
    <input type="radio" name="color" value="White">
    White
  </div>
  
  <!-- Size Selection -->
  <div ob-product-size="M">
    <input type="radio" name="size" value="M" checked>
    M
  </div>
  <div ob-product-size="L">
    <input type="radio" name="size" value="L">
    L
  </div>
  
  <!-- Quantity -->
  <div>
    <button ob-product-qty-minus>-</button>
    <span ob-product-qty-display>1</span>
    <button ob-product-qty-plus>+</button>
  </div>
  
  <!-- Add to Cart -->
  <button ob-cart-add>Add to Cart</button>
</div>

Cart Page

<!-- cart.html -->
<div ob-cart-page-list>
  <!-- Cart items will be dynamically loaded here -->
</div>

<div class="cart-total">
  <span>Total:</span>
  <span ob-cart-page-total>$0</span>
</div>

<a href="checkout.html">Proceed to Checkout</a>

<script src="cart-page.js"></script>

Product Gallery

<!-- Main Image -->
<img src="product-main.jpg" class="product_thumbnail" alt="Product">

<!-- Thumbnails -->
<div>
  <img src="product-1.jpg" class="product_gallery_image" alt="View 1">
  <img src="product-2.jpg" class="product_gallery_image" alt="View 2">
  <img src="product-3.jpg" class="product_gallery_image" alt="View 3">
</div>

<script src="product-gallery.js"></script>

🔧 API Reference

ObunduCart Class

// Access the cart instance
const cart = window.obunduCart;

// Get cart items
const items = cart.cart;

// Add item programmatically
cart.cart.push({
  id: 'prod-001-Black-M',
  name: 'Product Name',
  price: 100,
  quantity: 1,
  color: 'Black',
  size: 'M'
});
cart.saveCart();
cart.updateCartUI();

// Open/close cart
cart.openCart();
cart.closeCart();

CartPage Class

// Access the cart page instance
const cartPage = window.cartPage;

// Refresh cart display
cartPage.renderCart();

// Get cart items
const items = cartPage.cart;

ProductVariants Class

// Access variants instance
const variants = window.productVariants;

// Get current selection
const selection = variants.getSelection();
// Returns: { color: 'Black', size: 'M' }

💾 Data Structure

Cart items are stored in localStorage as:

{
  id: "prod-001-Black-M",        // Unique variant ID
  baseId: "prod-001",             // Original product ID
  name: "Contemporary Kimono Jacket",
  price: 450,
  image: "https://...",
  color: "Black",
  size: "M",
  quantity: 1
}

🎨 Styling

The system uses CSS classes for styling. Include the provided CSS or create your own:

<link rel="stylesheet" href="cart-popup.css">

Key classes:

• .cart-popup - Main popup container
• .cart-item - Individual cart item
• .cart-qty-controls - Quantity buttons
• .cart-checkout-btn - Checkout button

🌐 Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

📝 License

MIT License - feel free to use in your projects!

🤝 Contributing

Contributions welcome! Please open an issue or submit a pull request.

📧 Support

For issues or questions:

• GitHub Issues: https://github.com/obundu/cart-system/issues
• Email: [email protected]

🔗 Links

• Documentation
• Examples
• Changelog

Made with ❤️ by Obundu Collective