Setting the file. One moment.
Popups · Storefront Best Practices · medusajs/medusa-agent-skills · Skills Docs
Back to the top of the page Mcloud
Popups (modals/overlays) appear over main content to capture attention for specific actions: newsletter signups, promotional offers, exit-intent offers.
Assumed knowledge : AI agents know how to build modals with close buttons and backdrop overlays. This focuses on ecommerce popup patterns.
Critical balance : Effective for conversions when used sparingly, intrusive and annoying when overused. Timing and frequency are critical for ecommerce.
Offering significant value (10-20% first-purchase discount, free shipping)
Time-sensitive promotions (flash sale ending soon)
Exit-intent to recover abandoning visitors (last chance offer)
First-time visitor welcome (one-time only)
Important announcements (shipping delays, policy changes)
Every page visit (extremely annoying)
Multiple popups per session
Immediate page load (users haven’t seen site yet)
Mobile users (especially full-screen takeovers - very disruptive)
Users who already signed up or dismissed
Top banner: Less intrusive, always visible, good for ongoing promotions
Inline forms: Homepage or footer newsletter signup, non-blocking
Slide-in (corner): From bottom-right, less disruptive than center popup
Post-purchase: Ask for email after successful order (high conversion)
Popups are best when: Need immediate attention, high-value offer justifies interruption, exit-intent (last chance).
Purpose : Convert first-time visitors with discount incentive.
Headline: “Welcome! Get 10% Off Your First Order”
Email input
Discount code or automatic application
Subscribe button: “Get My Discount”
Timing : After 30-60 seconds on site OR after viewing 2-3 products (engagement signal).
Frequency : Once per user (cookie/localStorage). Don’t show to returning customers.
Purpose : Grow email list for marketing.
Value proposition: “Get exclusive deals and early access”
Email input
Subscribe button
Optional: First-purchase discount incentive (10-15% off)
Timing : After 50% scroll OR 60 seconds on site.
Frequency : Once per session. If dismissed, don’t show for 30 days.
Purpose : Recover abandoning visitors with last-chance offer.
Trigger : Mouse moves toward browser close/back button (desktop only).
Urgency: “Wait! Don’t Miss Out”
Offer: “Take 10% Off Your Order” or “Free Shipping Today Only”
Email capture (optional): “Send me the code”
CTA: “Claim Offer” or “Continue Shopping”
Best for : Cart abandoners, product page exits, first-time visitors.
Frequency : Once per session. Don’t show if user already added to cart or on checkout.
Purpose : Remind user of items in cart before leaving.
Trigger : Exit-intent when cart has items but user navigating away.
“Your Cart is Waiting”
Show cart summary (items, total)
CTA: “Complete Your Order” or “View Cart”
Optional incentive: “Complete in 10 minutes for free shipping”
Frequency : Once per session with items in cart.
Purpose : Announce sales, new arrivals, or site-wide events.
Headline: “Flash Sale: 40% Off Everything”
Subtext: “Ends in 3 hours”
CTA: “Shop Now”
Timing : Immediate on page load (if major event), OR after 30 seconds.
Frequency : Once per day during promotion period.
30-60 seconds after page load (enough time to browse)
Never immediate (0 seconds) - users need to see site first
After 50% scroll (shows interest)
After viewing 2-3 products (qualified visitor)
After adding to cart (exit-intent only)
Mouse moves toward close/back button (desktop)
Scroll-up toward address bar (mobile - less reliable)
Only trigger once per session
Don’t trigger on checkout pages (interrupts purchase)
Homepage: Welcome/discount popup
Product pages: Exit-intent with product-specific offer
Cart page: Don’t use popups (already engaged)
Checkout: Never use popups (critical flow)
Critical for UX : Don’t show same popup repeatedly to same user.
Cookie/localStorage tracking : Store dismissal/signup with timestampRespect dismissals : If user closes popup, don’t show for 30 daysSigned-up users : Never show newsletter popup againSession limits : Max 1 popup per sessionTime cooldown : If dismissed, wait 30 days before showing again
Session 1: Welcome discount popup
Session 2+: Exit-intent only (if applicable)
Never stack multiple popups
Mobile popups are MORE intrusive:
Smaller screen = popup takes more space
Harder to close (small X button)
Disrupts mobile browsing flow
Can hurt mobile SEO (Google penalty for intrusive interstitials)
Use sparingly : Consider top banner or inline forms insteadMake easily dismissable : Large close button (44x44px), tap outside to closeDelay longer : 60+ seconds instead of 30 secondsSmaller size : 90% width max, not full-screenExit-intent : Less reliable on mobile, avoidGoogle penalty : Avoid full-screen popups on mobile (hurts rankings) Mobile alternative : Sticky bottom bar (less intrusive)
“Get 10% Off - Sign Up” with email input
Always visible but doesn’t block content
Better mobile UX than popup
Not done: Clear value proposition (discount, benefit)Not done: Single focused CTANot done: Easy to close (X button, backdrop click, Escape key)Not done: Delayed timing (30-60s, not immediate)Not done: Frequency management (localStorage/cookie tracking)Not done: Respect dismissals (30-day cooldown)Not done: Never show to signed-up usersNot done: Max 1 popup per sessionNot done: Exit-intent for cart abandoners (desktop only)Not done: Don’t show on checkout pagesNot done: Mobile: Use sparingly, consider alternativesNot done: Mobile: Large close button (44x44px)Not done: Mobile: Not full-screen (90% width max)Not done: Email validation before submitNot done: Loading state on submitNot done: Success message or redirectNot done: Keyboard accessible (Tab, Escape, Enter)Not done: role="dialog" and aria-modal="true"Not done: Focus trap (keep focus within popup)Not done: ARIA label on close buttonNot done: Screen reader announcements on open reference/components/popups.md