Setting the file. One moment. Mcloud
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
- On cart icon click (always) - Click cart icon in navbar opens popup
- After adding to cart (recommended) - Auto-open popup when item added, confirms action, allows checkout or continue shopping
- 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
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
- Header: Title + item count + close button (optional for dropdown)
- Scrollable content: List of cart items
- Sticky footer: Subtotal + action buttons (Checkout, View Cart)
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
- On app initialization (update cart icon badge)
- On popup open (show loading state)
- After cart updates (add/remove/change quantity)
- 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
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)
- 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
- Usually NOT in cart popup (too cramped)
- Reserve for full cart page
- Exception: Simple code input if space permits
- Checkout (primary) - Most prominent, high contrast (brand color), navigates to checkout
- View Cart (secondary) - Outline or subtle, navigates to full cart page
Both buttons full-width, 44-48px height on mobile.
Show icon/illustration + “Your cart is empty” + “Continue Shopping” button. Centered, friendly, minimal design.
On popup open: Show skeleton/placeholder while fetching (avoid blank screen)
- 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…”)
- 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.
- Full-width (100% minus margins)
- Max height 60-70% viewport, scrollable
- Tap outside to close
- 85-95% screen width or full screen
- Slides from right or bottom
- Swipe to close gesture supported
- Backdrop overlay
- 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)
- Not done: Opens on cart icon click
- Not done: Dropdown (280-320px) or drawer (320-400px) layout
- Not done: Close button or click outside to close
- Not done: Backdrop overlay if drawer
- Not done: CRITICAL: Cart items show variant details (size, color, etc.) - not just product title
- Not done: Cart items with image, title, variant options, quantity, prices
- Not done: Quantity controls (+/- buttons, debounced)
- Not done: Remove item button
- Not done: Subtotal displayed
- Not done: Checkout button (primary)
- Not done: View Cart button (secondary)
- Not done: Empty state with “Continue Shopping” CTA
- Not done: Loading states (skeleton/spinner)
- Not done: Smooth animations (250-350ms)
- Not done: Mobile: Full-width dropdown or 85-95% drawer
- Not done: Touch targets 44-48px minimum
- Not done:
role="dialog" and aria-modal="true"
- Not done: ARIA labels on cart button (“Shopping cart with 3 items”)
- Not done: Keyboard accessible (focus trap, Escape closes, return focus)
- Not done: Screen reader announcements (item added/removed)
- Not done: Real-time cart count badge updates
reference/components/cart-popup.md