4.6 KiB
Product Card Component
Contents
- Overview
- Price Display (Ecommerce-Specific)
- Action Buttons and Variant Handling
- Badges and Labels
- Mobile Considerations
- Ecommerce Checklist
Overview
Product cards display products in grids (product listings, search results, related products). Key ecommerce considerations: clear pricing, quick add-to-cart, and stock indicators.
Assumed knowledge: AI agents know how to build cards with images, titles, and buttons. This guide focuses on ecommerce-specific patterns.
Key Ecommerce Requirements
- Clear, prominent pricing (including sale prices)
- Variant handling for add-to-cart
- Stock status indicators
- Sale/New/Out of Stock badges
- Responsive grid (1 col mobile, 2-3 tablet, 3-4 desktop)
- Fast image loading (lazy load, optimized)
Price Display (Ecommerce-Specific)
Regular vs Sale Pricing
Sale price display:
- Sale price: Larger, bold, red or accent color
- Original price: Smaller, struck through (
$79.99), gray - Position sale price before original price
- Optional: Show discount percentage badge (-20%)
Format consistently:
- Always include currency symbol ($49.99)
- Consistent decimals ($49.99 not $49.9 or $50)
- For Medusa: Display prices as-is (no divide by 100)
Price Range (Multiple Variants)
When variants have different prices:
- Show "From $49" or "$49 - $79"
- Makes it clear price varies by selection
- Don't show range if all variants same price
Action Buttons and Variant Handling
Add to Cart with Variants (CRITICAL)
Key challenge: Products with variants require variant selection before adding to cart.
Handling strategies:
- Add first variant by default - Click adds
product.variants[0]. Fast for simple products (1-2 variants). - Redirect to product page - Navigate to detail page for variant selection. Best for complex products (size + color + material).
- Quick View modal - Variant selector in modal. Good middle ground (desktop only).
Decision:
- Simple products (1-2 variants): Add first variant
- Fashion/apparel with sizes: Require size selection (redirect or Quick View)
- Complex products (3+ variant types): Redirect to product page
Button behavior:
- Loading state ("Adding..."), disable during loading
- Optimistic UI update (cart count immediately)
- Success feedback (toast, cart popup, or checkmark)
- Don't navigate away (stay on listing page)
- Handle errors (out of stock, API failure)
Wishlist button (optional): Heart icon, top-right over image. Empty when not saved, filled (red) when saved. Refer to wishlist.md for more details.
Badges and Labels
Badge priority (show max 1-2 per card):
- Out of Stock (highest) - Gray/black overlay on image, disables add-to-cart
- Sale/Discount - "Sale" or "-20%", red/accent, top-left corner
- New - "New" for recent products, blue/green, top-left corner
- Low Stock (optional) - "Only 3 left", orange, creates urgency
Display: Top-left corner (except Out of Stock overlay), small but readable, high contrast.
Mobile Considerations
Grid Layout
Mobile-specific adjustments:
- 2 columns maximum on mobile (never 3+)
- Larger touch targets (44px minimum for buttons)
- Always show "Add to Cart" button (no hover-only)
- Simplified content (hide optional elements like brand)
- Smaller images for performance (<400px wide)
Touch Interactions
No hover states on mobile:
- Don't hide actions behind hover
- Always show primary button
- Use tap states (active state) instead of hover
Ecommerce Checklist
Essential features:
- Clear product image (optimized, lazy loaded)
- Product title (truncated to 2 lines max)
- Price prominently displayed
- Sale price shown correctly (struck-through original price)
- Currency symbol included
- For Medusa: Price displayed as-is (not divided by 100)
- Add to Cart button with loading state
- Variant handling strategy (first variant, redirect, or Quick View)
- Optimistic UI update (cart count immediately)
- Success feedback (toast or cart popup)
- Don't navigate away after adding to cart
- Out of Stock badge (disables add-to-cart)
- Sale badge when price reduced
- Responsive grid (1 col mobile, 2-3 tablet, 3-4 desktop)
- Touch-friendly on mobile (44px buttons)
- Keyboard accessible (focus states, Enter to activate)
- Descriptive alt text on images
- Semantic HTML (
<article>wrapper)