190 lines
7.0 KiB
Markdown
190 lines
7.0 KiB
Markdown
# Cart Popup Component
|
||
|
||
## Contents
|
||
|
||
- [Overview](#overview)
|
||
- [When to Show Cart Popup](#when-to-show-cart-popup)
|
||
- [Layout Patterns](#layout-patterns)
|
||
- [Cart Display](#cart-display)
|
||
- [Actions and CTAs](#actions-and-ctas)
|
||
- [Empty State](#empty-state)
|
||
- [Mobile Considerations](#mobile-considerations)
|
||
- [Checklist](#checklist)
|
||
|
||
## Overview
|
||
|
||
Cart popup (mini cart/cart drawer) shows quick cart overview without navigating away. Opens from cart icon click or after adding items.
|
||
|
||
**⚠️ CRITICAL: Always display variant details (size, color, material, etc.) in cart popup, not just product titles.**
|
||
|
||
**Assumed knowledge**: AI agents know how to build modals, dialogs, and overlays. This focuses on ecommerce-specific patterns.
|
||
|
||
**Cart popup vs full cart page:**
|
||
- Popup: Quick overview, fast checkout path, continue shopping easily
|
||
- Full page: Detailed review, promo codes, complex operations
|
||
- **Recommended**: Both - popup for speed, full cart page for details
|
||
|
||
## When to Show Cart Popup
|
||
|
||
**Trigger options:**
|
||
|
||
1. **On cart icon click** (always) - Click cart icon in navbar opens popup
|
||
2. **After adding to cart** (recommended) - Auto-open popup when item added, confirms action, allows checkout or continue shopping
|
||
3. **Hover cart icon** (desktop only, optional) - Quick peek on hover. Can be accidental, not recommended.
|
||
|
||
**Add-to-cart feedback alternatives:**
|
||
- Show popup (most common) - Immediate confirmation, clear path to checkout
|
||
- Toast only (less intrusive) - Small notification, user clicks cart icon to see details
|
||
- Navigate to cart page (traditional) - Goes directly to full cart page, less common now
|
||
|
||
## Layout Patterns
|
||
|
||
**Two common patterns:**
|
||
|
||
**1. Dropdown (recommended for simplicity):**
|
||
- Drops down from cart icon, positioned below navbar
|
||
- Width: 280-320px, max height with scroll
|
||
- No backdrop overlay (click outside to close)
|
||
- Better for few items, simpler implementation
|
||
|
||
**2. Slide-in drawer (more prominent):**
|
||
- Slides from right, full height, width 320-400px (desktop) or 80-90% (mobile)
|
||
- Semi-transparent backdrop overlay (click to close)
|
||
- Better for multiple items or complex carts
|
||
|
||
**Both patterns have:**
|
||
- Header: Title + item count + close button (optional for dropdown)
|
||
- Scrollable content: List of cart items
|
||
- Sticky footer: Subtotal + action buttons (Checkout, View Cart)
|
||
|
||
## Cart Display
|
||
|
||
**Fetch cart data from backend:**
|
||
- Cart ID from localStorage
|
||
- Line items (products, variants, quantities, prices)
|
||
- Cart totals (subtotal, tax, shipping)
|
||
- See connecting-to-backend.md for backend integration
|
||
|
||
**When to fetch:**
|
||
- On app initialization (update cart icon badge)
|
||
- On popup open (show loading state)
|
||
- After cart updates (add/remove/change quantity)
|
||
|
||
**State management:**
|
||
- Store cart data globally (React Context or TanStack Query)
|
||
- Persist cart ID in localStorage
|
||
- Optimistic UI updates (update immediately, revert on error)
|
||
- **CRITICAL: Clear cart state after order is placed** - See connecting-to-backend.md for cart cleanup pattern
|
||
- Common issue: Cart popup shows old items after checkout because cart state wasn't cleared
|
||
- See connecting-to-backend.md for cart state patterns
|
||
|
||
**Cart item display:**
|
||
|
||
**CRITICAL: Always show variant details (size, color, material, etc.) for each cart item.**
|
||
|
||
Without variant details, users can't confirm they added the correct variant. This is especially critical when products have multiple options.
|
||
|
||
- Product image (60-80px thumbnail)
|
||
- Product title (truncated to 2 lines)
|
||
- **Variant details (REQUIRED)**: Size, color, material, or other variant options
|
||
- Format: "Size: Large, Color: Black" or "Large / Black"
|
||
- Show ALL selected variant options, not just product title
|
||
- Display below title, smaller text (gray)
|
||
- Quantity controls (+/- buttons, debounce 300-500ms)
|
||
- Unit price and total price (line item total = price × quantity)
|
||
- Remove button (X icon, no confirmation needed)
|
||
|
||
**Why variant details are critical:**
|
||
- User confirmation: "Did I add the right size?"
|
||
- Prevents cart abandonment from uncertainty
|
||
- Allows corrections before checkout
|
||
- Essential for products with multiple variants (clothing, shoes, configurable products)
|
||
|
||
## Actions and CTAs
|
||
|
||
**Cart summary display:**
|
||
- Subtotal (sum of all items)
|
||
- Shipping and tax: "Calculated at checkout" or actual amount
|
||
- Total: Bold and prominent
|
||
|
||
**Free shipping indicator (optional):**
|
||
- "Add $25 more for free shipping" with progress bar
|
||
- Encourages larger orders, updates as cart changes
|
||
|
||
**Promo codes:**
|
||
- Usually NOT in cart popup (too cramped)
|
||
- Reserve for full cart page
|
||
- Exception: Simple code input if space permits
|
||
|
||
**Action buttons:**
|
||
1. **Checkout** (primary) - Most prominent, high contrast (brand color), navigates to checkout
|
||
2. **View Cart** (secondary) - Outline or subtle, navigates to full cart page
|
||
|
||
Both buttons full-width, 44-48px height on mobile.
|
||
|
||
## Empty State
|
||
|
||
Show icon/illustration + "Your cart is empty" + "Continue Shopping" button. Centered, friendly, minimal design.
|
||
|
||
## Loading and Error States
|
||
|
||
**On popup open**: Show skeleton/placeholder while fetching (avoid blank screen)
|
||
|
||
**During updates**:
|
||
- Quantity changes: Inline spinner, disable controls, debounce 300-500ms
|
||
- Item removal: Fade out animation, disable remove button during request
|
||
- Add to cart: Loading indicator on button ("Adding...")
|
||
|
||
**Error handling**:
|
||
- Network errors: Show retry option, don't close popup
|
||
- Invalid cart ID: Create new cart automatically
|
||
- Out of stock: Disable quantity increase, show message
|
||
- Revert optimistic updates on failure
|
||
|
||
**Animations**: Smooth transitions (250-350ms), slide-in drawer, backdrop fade-in/out. Highlight newly added items.
|
||
|
||
## Mobile Considerations
|
||
|
||
**Dropdown on mobile:**
|
||
- Full-width (100% minus margins)
|
||
- Max height 60-70% viewport, scrollable
|
||
- Tap outside to close
|
||
|
||
**Drawer on mobile:**
|
||
- 85-95% screen width or full screen
|
||
- Slides from right or bottom
|
||
- Swipe to close gesture supported
|
||
- Backdrop overlay
|
||
|
||
**Mobile adjustments:**
|
||
- Large touch targets (44-48px minimum)
|
||
- Full-width action buttons (48-52px height)
|
||
- Smaller images (60px), truncate titles
|
||
- Sticky footer with actions
|
||
- Large close button (44x44px)
|
||
|
||
## Checklist
|
||
|
||
**Essential features:**
|
||
- [ ] Opens on cart icon click
|
||
- [ ] Dropdown (280-320px) or drawer (320-400px) layout
|
||
- [ ] Close button or click outside to close
|
||
- [ ] Backdrop overlay if drawer
|
||
- [ ] **CRITICAL: Cart items show variant details (size, color, etc.) - not just product title**
|
||
- [ ] Cart items with image, title, variant options, quantity, prices
|
||
- [ ] Quantity controls (+/- buttons, debounced)
|
||
- [ ] Remove item button
|
||
- [ ] Subtotal displayed
|
||
- [ ] Checkout button (primary)
|
||
- [ ] View Cart button (secondary)
|
||
- [ ] Empty state with "Continue Shopping" CTA
|
||
- [ ] Loading states (skeleton/spinner)
|
||
- [ ] Smooth animations (250-350ms)
|
||
- [ ] Mobile: Full-width dropdown or 85-95% drawer
|
||
- [ ] Touch targets 44-48px minimum
|
||
- [ ] `role="dialog"` and `aria-modal="true"`
|
||
- [ ] ARIA labels on cart button ("Shopping cart with 3 items")
|
||
- [ ] Keyboard accessible (focus trap, Escape closes, return focus)
|
||
- [ ] Screen reader announcements (item added/removed)
|
||
- [ ] Real-time cart count badge updates
|