Skip to main content

​
What It Does

The Newsletter Modal displays a popup overlay prompting visitors to subscribe to your email newsletter. The modal appears automatically after a specified delay (default 3 seconds) and intelligently remembers visitor interactions using cookies—if a visitor closes the modal, they won’t see it again for the duration you specify (default 365 days). Fully customizable with your own heading, content, image, and colors, the newsletter modal integrates seamlessly with Shopify’s customer email collection system. Perfect for growing your email list, announcing first-purchase discounts, or promoting exclusive content.

​
Getting Started

1

Add the Section

Add the Newsletter Modal section to your theme (typically added once globally, not per-page)
2

Enable the Modal

Check “Enable newsletter modal” to activate popup (unchecked hides it site-wide)
3

Customize Content

Set heading (“Enjoy 10% off your first order”), content (signup pitch), and optional image
4

Configure Timing

Set delay (seconds before popup appears) and cookie expiration (days before showing again if closed)

​
Settings

Type: Checkbox
Default: Enabled (checked)Master switch controlling whether the newsletter modal appears on your site.

​
When Enabled (Checked)

  • Modal appears to visitors after configured delay
  • Displays on all pages site-wide (not page-specific)
  • Respects cookie settings (won’t show if visitor previously closed it)
  • Integrates with age verification (waits until age verified if both active)

​
When Disabled (Unchecked)

  • Modal never appears on site
  • Useful for:
    • Temporarily pausing newsletter campaign
    • Testing other popups (age verification, sales banners)
    • Seasonal campaigns (enable during busy season, disable off-season)
    • Website maintenance (hide while updating content)

​
Quick Toggle Use Cases

Enable during:
  • Product launches (capture interest from launch traffic)
  • Holiday shopping seasons (Black Friday, Christmas)
  • Marketing campaigns (social media promotion driving traffic)
  • After redesign (re-engage visitors with fresh offer)
Disable during:
  • Site issues (don’t interrupt frustrated visitors)
  • Post-sale fatigue (give customers a break after major sale)
  • Low-traffic periods (off-season for seasonal businesses)
  • Testing other high-priority popups
Best practice: Enable for active growth periods, disable when you need visitor focus elsewhere.
Type: Checkbox
Default: Disabled (unchecked)
Info: “When checked, the modal will open whenever you are in the Theme Customizer, and customizing the section’s settings would instantly render its contents in the editor. Note that you should deselect that option after you’ve finished customizing the modal, so that the modal can be closed”Controls whether the modal displays while you’re editing the theme in Shopify’s customizer.

​
When to Enable (Check)

Enable when:
  • Actively editing modal content (heading, text, image)
  • Customizing colors (background, text colors)
  • Testing layout (image flip, content alignment)
  • Setting up modal for first time
  • Want to see changes immediately as you edit
Behavior when enabled:
  • Modal opens automatically in Theme Customizer
  • Updates instantly when you change settings
  • Live preview of colors, text, images
  • Blocks view of page content below (intentional for preview)

​
When to Disable (Uncheck)

Disable when:
  • Finished customizing modal
  • Editing other sections (modal blocks view)
  • Working on navigation, header, product pages
  • Want to close modal to see overall page layout
Behavior when disabled:
  • Modal hidden in Theme Customizer (doesn’t block your work)
  • Modal still accessible in section list for editing settings
  • Modal still appears on live site (this only affects editor)

​
Workflow Best Practice

  1. Enable toggle when starting modal customization
  2. Edit content, upload image, adjust colors
  3. Preview appearance with different content lengths
  4. Disable toggle when satisfied with design
  5. Continue editing other theme sections
  6. Test modal on live site (preview theme in incognito mode)
Important: This setting only affects Theme Customizer. Live site behavior is controlled by “Enable newsletter modal” setting, not this toggle.Recommendation: Enable only while actively editing modal, disable immediately after to avoid blocking other work.
Type: Range slider
Range: 1-60 seconds (step: 1 second)
Default: 3 secondsControls how long to wait after page load before displaying the newsletter modal.

​
How Delay Works

Timing starts:
  • When page finishes loading (DOM ready)
  • Countdown begins 1-60 seconds (your choice)
  • Modal appears after countdown completes
If visitor navigates away:
  • Timer resets on new page
  • Each page load has its own delay timer
  • Modal shows on whichever page visitor stays on long enough

​
Choosing Optimal Delay

Short delay (1-3 seconds): ← Default: 3s
  • Pro: Captures attention immediately
  • Con: May feel intrusive if visitor just arrived
  • Best for: High-traffic campaigns, limited-time offers, returning visitors
  • User experience: “I just got here, already asking for email?”
Medium delay (5-10 seconds):
  • Pro: Visitor has time to see content before interruption
  • Con: Some visitors may leave before modal appears
  • Best for: General newsletter signup, evergreen campaigns
  • User experience: “I’ve browsed a bit, this offer seems interesting”
Long delay (15-30 seconds):
  • Pro: Visitor demonstrates interest by staying, less intrusive
  • Con: High bounce rate means many never see modal
  • Best for: High-value offers, content-rich sites, blogs
  • User experience: “I’m engaged with content, tell me more”
Very long delay (30-60 seconds):
  • Pro: Highly engaged visitors only (low annoyance factor)
  • Con: Very few visitors will see modal (low conversion volume)
  • Best for: Niche audiences, loyalty programs, premium content
  • User experience: “I’m clearly interested, yes I’ll subscribe”
Goal: Maximum signups (volume):
  • Delay: 3-5 seconds
  • Rationale: Balance between reach and annoyance
Goal: Quality leads (engaged visitors):
  • Delay: 10-15 seconds
  • Rationale: Filters for visitors who spend time on site
Goal: Minimal annoyance (brand perception):
  • Delay: 20-30 seconds
  • Rationale: Only interrupts committed browsers
Goal: Capture bouncing visitors (exit intent alternative):
  • Delay: 5-8 seconds
  • Rationale: Early enough to catch quick browsers

​
Testing & Optimization

Start with default: 3 seconds is proven baseline A/B test delays: Try 3s vs 10s, measure signup rate Monitor bounce rate: If spikes, delay may be too aggressive Segment audiences: Longer delay for returning visitors (requires custom code)Recommendation: Start with 3-5 seconds, increase to 10-15s if visitors report annoyance.
Type: Color picker
Default: #FFFFFF (white)Sets the background color of the newsletter modal.

​
Choosing Background Color

White (#FFFFFF): ← Default
  • Clean, professional, high readability
  • Works with most brand colors
  • Doesn’t distract from content/image
  • Safe choice for any brand
Brand color (your primary):
  • Strong brand recognition
  • Bold, attention-grabbing
  • Ensure text remains readable (use “Primary Text Color” to adjust)
  • Example: Bright blue brand (#007BFF)
Soft neutral (light gray, beige):
  • Subtle, elegant, less harsh than white
  • Good for luxury/minimalist brands
  • Examples: #F5F5F5 (light gray), #FAF9F6 (off-white)
Dark background (#000000, dark gray):
  • Modern, bold, high-contrast
  • Requires light text colors (white/cream)
  • Dramatic for premium brands
  • Example: #1A1A1A (near-black)

​
Color Psychology

  • White: Clean, trustworthy, medical/health (neutral)
  • Blue: Calm, reliable, tech-friendly
  • Green: Natural, eco-friendly, growth
  • Red: Urgency, excitement, danger (use sparingly)
  • Black: Luxury, premium, sophisticated
  • Yellow: Cheerful, optimistic, attention-grabbing

​
Accessibility Considerations

Contrast ratio:
  • Background + text must meet WCAG contrast requirements (4.5:1 minimum)
  • Use “Primary Text Color” setting to ensure readability
  • Test: Squint at preview—can you read text easily?
Best combinations:
  • White background + black text (highest contrast)
  • Dark background + white text (high contrast)
  • Light background + dark text (good contrast)
  • Avoid: Medium background + medium text (poor contrast)
Recommendation: Start with white (#FFFFFF), adjust to brand color only if text remains highly readable.
Type: Color picker
Default: #000000 (black)Sets the color for the main heading text in the newsletter modal.

​
When to Adjust

Keep default black (#000000) when:
  • Background is white or very light
  • Maximum readability is priority
  • Brand is minimalist/modern
Change to white (#FFFFFF) when:
  • Background is dark (black, navy, dark gray)
  • Using brand dark background color
  • Need high contrast on dark
Use brand color when:
  • Background is neutral (allows brand color to pop)
  • Brand color has sufficient contrast with background
  • Example: Orange heading (#FF6600) on white background

​
Contrast Guidelines

High contrast (recommended):
  • Black text on white background
  • White text on black background
  • Dark blue text on light background
Medium contrast (use cautiously):
  • Dark gray text on white background
  • Light text on medium dark background
  • May fail accessibility standards
Low contrast (avoid):
  • Light gray text on white background
  • Medium gray text on medium background
  • Difficult to read, fails accessibility
Test your combination:
  • Preview modal after selecting colors
  • Squint test: Can you read heading easily?
  • Accessibility check: Use WebAIM Contrast Checker
Recommendation: Use black (#000000) for light backgrounds, white (#FFFFFF) for dark backgrounds.
Type: Color picker
Default: #666666 (medium gray)Sets the color for the body content text (your signup pitch paragraph).

​
Purpose of Secondary Text

Secondary text is typically:
  • Less prominent than heading (lighter/softer)
  • Used for body copy, descriptions, fine print
  • Readable but doesn’t compete with heading for attention

​
Default Gray (#666666)

Why medium gray:
  • Creates visual hierarchy (heading stands out more)
  • Still readable on white background (meets accessibility standards)
  • Professional, not distracting
  • Standard web convention

​
When to Change

Use darker gray (#333333) when:
  • You want body text more prominent
  • Content is critical to conversion
  • Background is very light
Use lighter gray (#999999) when:
  • You want heading to dominate
  • Body text is supplementary only
  • Risk: May be too light (test readability)
Use white (#FFFFFF) when:
  • Background is dark
  • Need high contrast
  • Both heading and body need maximum readability
Use brand color when:
  • Background allows it (neutral white/gray)
  • Brand color is dark enough for readability
  • Example: Dark green (#006400) body text on white

​
Hierarchy Best Practices

Heading should be darker/bolder than body:
  • Heading: #000000 (black)
  • Body: #666666 (medium gray)
  • Creates clear visual hierarchy
Avoid equal weight:
  • Don’t use same color for heading and body
  • Lack of hierarchy confuses visual flow
Test together:
  • Preview heading + body with your chosen colors
  • Heading should draw attention first, body should be readable second
Recommendation: Keep default #666666 for most use cases. Adjust to #333333 if body text is important, #FFFFFF if background is dark.
Type: Checkbox
Default: Unchecked (image left, content right)Controls whether the image appears on the left or right side of the modal on desktop.

​
Layout Options

Unchecked (Default - Image Left):
Desktop:
[Image] | [Heading + Content + Form]
  • Image on left, content on right
  • Standard reading flow (left to right in Western cultures)
  • Visual first, then message
Checked (Flipped - Image Right):
Desktop:
[Heading + Content + Form] | [Image]
  • Content on left, image on right
  • Text-first approach (message before visual)
  • Less common but can work for text-heavy pitches

​
Mobile Behavior

Both layouts on mobile:
  • Image always stacks on top
  • Content always below image
  • Flip setting has no effect on mobile
  • Single column layout regardless

​
When to Flip

Keep default (image left) when:
  • Image is strong visual hook (product, lifestyle photo)
  • You want visual to grab attention first
  • Following standard web convention
Flip (image right) when:
  • Heading/message is most important (text-first)
  • Image is decorative rather than primary hook
  • A/B testing layout variations
  • Specific design preference (less common)

​
Without Image

If no image uploaded:
  • Content centered in modal
  • Flip setting has no effect (nothing to flip)
  • Content occupies full modal width
Recommendation: Keep unchecked (default) for standard image-left layout. Flip only for specific design reasons or A/B testing.
Type: Textarea
Default: “Enjoy 10% off your first order.”Main heading displayed prominently at top of newsletter modal.

​
Crafting Effective Headings

Heading components:
  1. Value proposition: What visitor gets (discount, exclusive content, early access)
  2. Urgency/incentive: Why subscribe now (limited time, first order)
  3. Brevity: Short enough to scan quickly (5-10 words ideal)

​
Heading Examples by Offer Type

Discount offers:
  • “Enjoy 10% off your first order” (default)
  • “Get 15% off when you subscribe”
  • “Welcome! Take 20% off today”
  • “New friend discount: 10% off”
Exclusive access:
  • “Join the club for exclusive perks”
  • “Get early access to new arrivals”
  • “Subscribe for VIP-only deals”
  • “Unlock members-only styles”
Free shipping:
  • “Subscribe and enjoy free shipping”
  • “Get free delivery on every order”
  • “Join now for forever-free shipping”
Content/updates:
  • “Stay in the loop with weekly updates”
  • “Get the latest trends in your inbox”
  • “Join 10,000+ subscribers”
  • “Subscribe for style inspiration”
Product launches:
  • “Be the first to know about new drops”
  • “Get notified when we restock”
  • “New arrivals delivered to your inbox”

​
Headline Formulas

Value + Action:
  • “Save 10% + join our community”
  • “Subscribe + get free shipping”
Benefit + Reason:
  • “Enjoy 15% off your first purchase”
  • “Get exclusive access to sales”
Urgency:
  • “Limited time: 20% off”
  • “Don’t miss out—subscribe today”
Social proof:
  • “Join 50,000+ happy subscribers”
  • “See why everyone’s subscribing”

​
Best Practices

Be specific: “10% off” better than “special discount” Lead with benefit: What they get, not what you want Keep short: 5-10 words (fits on one line) Avoid jargon: Simple language converts better Test variations: A/B test different offers (10% vs free shipping)Recommendation: Start with default (“Enjoy 10% off your first order”), adjust to match your specific offer.
Type: Rich text
Default: “Sign up to join the club and get 10% off your purchase! Our selection of products is vast and offers something for everyone. Shop now and save.”Body text below heading, providing additional context or persuasion for signup.

​
Content Purpose

Use content to:
  • Expand on heading: Provide details about offer
  • Build trust: Explain what subscriber receives (no spam, weekly updates, etc.)
  • Add urgency: Limited time, exclusive access
  • Describe benefit: Save money, stay informed, get early access

​
Content Length

Short (1-2 sentences): ← Recommended
  • Quick to scan, doesn’t overwhelm
  • Works best on mobile (limited space)
  • Example: “Sign up today and save 10% on your first order. Plus, get early access to sales!”
Medium (3-4 sentences):
  • Provides more context/persuasion
  • Risk: Visitors may not read all
  • Example: “Join our mailing list to receive 10% off your first purchase. You’ll also get early access to new arrivals, exclusive sales, and style tips. We only send quality emails—no spam, ever.”
Long (5+ sentences):
  • Too much text, likely to be skipped
  • Avoid unless necessary (complex offers, legal requirements)

​
Content Examples

Discount offer: “Sign up today and enjoy 10% off your first order! Plus, be the first to hear about exclusive sales and new arrivals.”Exclusive access: “Join our VIP list for early access to new products, members-only sales, and style inspiration delivered weekly.”Transparency (builds trust): “Subscribe to get 10% off your first order. We’ll send you updates on new arrivals and sales—never spam. Unsubscribe anytime.”Social proof: “Join over 50,000 subscribers who enjoy 10% off, free shipping perks, and first dibs on new collections.”Free resource: “Download our free style guide and get weekly tips, trends, and exclusive offers delivered to your inbox.”

​
Rich Text Formatting

Bold for emphasis: “Sign up and get 10% off your first order—plus free shipping!”Multiple paragraphs (if needed):
Join our mailing list for 10% off your first purchase.

You'll also get early access to sales, new arrivals, and exclusive member perks.

​
Best Practices

Keep concise: 1-3 sentences ideal (mobile-friendly) Focus on “you”: Use “you get,” “you’ll receive” (customer-centric) Address objections: “No spam,” “Unsubscribe anytime” (builds trust) Reinforce heading: Expand on offer, don’t contradict it Test readability: Preview on mobile (text shouldn’t scroll)Recommendation: Use 1-2 sentences, highlight key benefit, address “what’s in it for me.”
Type: Image picker
Default: Empty (no image)Optional image displayed on left (or right if flipped) side of modal on desktop.

​
Image Purpose

Newsletter modal images serve to:
  • Attract attention: Visual hook before visitor reads text
  • Reinforce brand: Lifestyle, product, or brand imagery
  • Set tone: Luxury, playful, minimal, bold (matches brand personality)
  • Increase engagement: Modals with images often convert better

​
Image Specifications

Recommended size: 600x800px to 800x1000px (portrait/vertical)
  • Aspect ratio: 3:4 or 2:3 ideal (portrait orientation)
  • File format: JPG (photos), PNG (graphics)
  • File size: Under 200KB (modal should load quickly)
  • Color: Match brand colors or complement modal background color

​
Image Types

Product photography:
  • Show bestselling products or new arrivals
  • Single hero product or styled flat-lay
  • Best for: E-commerce stores, product-focused brands
Lifestyle imagery:
  • People using/wearing products
  • Aspirational scenes (travel, dining, fashion)
  • Best for: Fashion, home decor, lifestyle brands
Abstract/pattern:
  • Geometric patterns, textures, gradients
  • Minimal distraction, modern aesthetic
  • Best for: Tech, minimalist, contemporary brands
Graphic/illustration:
  • Custom illustrations, icons, brand mascots
  • Playful, distinctive, memorable
  • Best for: Creative brands, children’s products, unique aesthetics
Text-based image:
  • Large “10% OFF” or key message
  • Bold typography, minimal design
  • Best for: Sale promotions, urgent offers

​
With vs. Without Image

With image:
  • Desktop: Two-column layout (image + content)
  • Mobile: Image stacked above content
  • More visually engaging, takes up space
Without image (empty):
  • Desktop: Content centered, single column
  • Mobile: Content only, no stacking
  • Simpler, faster loading, text-focused

​
Layout Preview

Desktop with image:
[Image (30%)] | [Heading, Content, Form (70%)]
Mobile with image:
[Image full-width]
[Heading]
[Content]
[Form]
Desktop/Mobile without image:
[Heading centered]
[Content centered]
[Form centered]

​
Best Practices

Match brand: Use imagery consistent with website aesthetic Keep simple: Busy images distract from message Test performance: Large images slow modal load (compress files) Consider mobile: Image shrinks significantly on mobile (ensure it’s recognizable) Text-free images: Avoid text in image (use heading/content fields instead for accessibility)Recommendation: Use a simple product or lifestyle image (under 200KB) for visual interest, or leave empty for text-focused approach.

​
Best practices

Offer Clear Value

Lead with specific benefit (10% off, free shipping, exclusive access). Vague “join our newsletter” underperforms concrete offers.

Keep Content Concise

1-3 sentences maximum. Visitors won’t read paragraphs in a popup. Focus on key benefit and immediate CTA.

Test Delay Timing

Start with 3-5 seconds, monitor bounce rate. If visitors leave quickly, increase delay to 10-15 seconds for less intrusive timing.

Respect Cookie Expiration

90-180 days balances growth with respect. Too short (5-10 days) annoys frequent visitors. Remember browsers may shorten your setting.

Ensure High Contrast

Background and text colors must have strong contrast. Test on mobile and with accessibility tools—readability is critical to conversion.

Use Quality Images

If adding image, choose high-quality product or lifestyle photo under 200KB. Compress before uploading to avoid slow modal load.

Mobile-First Preview

70% of traffic is mobile. Preview modal on actual phone—text should be readable, image recognizable, buttons tappable.

A/B Test Offers

Test different incentives: 10% off vs free shipping vs exclusive access. Measure signup rate and customer lifetime value.

​
Common Use Cases

​
First-Purchase Discount (E-Commerce Standard)

Heading: “Enjoy 10% off your first order” Content: “Sign up today and save on your first purchase! Plus, get early access to sales and new arrivals.” Delay: 3 seconds (quick engagement) Cookie: 365 days (once a year max) Image: Hero product or lifestyle photo Best for: General e-commerce stores, fashion, home goods

​
Free Shipping Incentive

Heading: “Get free shipping on every order” Content: “Subscribe now and enjoy free delivery forever—plus exclusive member perks.” Delay: 5 seconds Cookie: 180 days (6 months) Image: Product packaging or delivery imagery Best for: Stores where shipping cost is barrier to purchase

​
Content/Blog Newsletter (No Discount)

Heading: “Join 10,000+ subscribers for weekly style tips” Content: “Get the latest trends, DIY projects, and exclusive tutorials delivered to your inbox every Friday.” Delay: 10 seconds (let them read content first) Cookie: 90 days (3 months) Image: Blog/content imagery or author photo Best for: Blogs, content sites, educators, influencers

​
Product Launch Announcement

Heading: “Be the first to know about new drops” Content: “Subscribe and get notified 24 hours before our new collections launch—VIP access only.” Delay: 5 seconds Cookie: 30 days (frequent reminders for launch season) Image: Teaser image of upcoming products Best for: Limited-release brands, streetwear, collectibles

​
Abandoned Cart Recovery Support

Heading: “Don’t leave empty-handed! Save 10%” Content: “Complete your purchase and save 10% today. Plus, join our mailing list for future deals.” Delay: 8 seconds (after they’ve browsed) Cookie: 7 days (short—encourage cart completion) Image: Product(s) from cart or similar items Best for: High-cart-abandonment stores, luxury items, considered purchases

​
Seasonal Campaign (Holiday, Sale)

Heading: “Holiday Sale: 20% off everything!” Content: “Subscribe now to unlock 20% off your order. Limited time only—don’t miss out!” Delay: 3 seconds (urgency) Cookie: 5-10 days (short—maximize reach during sale) Image: Holiday-themed imagery or sale products Best for: Black Friday, Christmas, seasonal sales

​
Layout Behavior

​
Desktop Layout

With image:
  • Two-column layout: Image (30% width) on left, content (70% width) on right
  • Image: Fills full height of modal
  • Content: Vertically centered (heading, text, form)
  • Modal dimensions: Max width ~750-800px
  • Flip option: Swaps image and content positions
Without image:
  • Single-column layout: Content centered in modal
  • Content: Heading, text, form stacked vertically
  • Modal dimensions: Narrower (max width ~500-600px)
  • Alignment: All content centered

​
Mobile Layout

Both layouts:
  • Single-column: Image stacks above content (if present)
  • Image height: ~200-300px (compressed from desktop)
  • Content: Full-width below image
  • Modal: Occupies most of screen (small margins)
  • Form: Full-width button

​
Visual Effects

Entrance animation:
  • Desktop: Fade in + scale up from 0.9 to 1.0
  • Mobile: Slide up from bottom of screen
  • Duration: ~300-400ms
  • Delay: Configured in “Add a delay in seconds” setting
Background overlay:
  • Color: Semi-transparent black (~50-70% opacity)
  • Blur: Optional backdrop blur (theme-dependent)
  • Interaction: Clicking overlay closes modal
  • Newsletter - Non-modal newsletter signup section (standard page section)
  • Age Verification Popup - Another modal (age verification takes priority over newsletter)
  • Footer - Alternative newsletter signup location (always visible)

​
Technical Notes

Cookie name: _newsletter_modal Cookie values:
  • none: Visitor closed modal, don’t show again
  • (empty/missing): Visitor hasn’t seen or closed modal, show it
Cookie attributes:
  • Expiration: Set by “Cookie expiration” setting (5-365 days)
  • Path: / (applies site-wide)
  • Secure: May be set depending on HTTPS (best practice)
Browser limitations:
  • Safari ITP: May limit to 7 days regardless of setting
  • Firefox ETP: May limit to 24 hours in strict mode
  • Private browsing: All cookies deleted on browser close

​
Age Verification Integration

If both Age Verification Popup and Newsletter Modal are enabled:
  1. Age verification shows first: Newsletter modal waits
  2. After age confirmation: Newsletter modal delay timer starts
  3. If age declined: Newsletter modal never shows (visitor leaves site)
JavaScript coordination:
  • Newsletter modal checks getCookie("age-verified")
  • Only proceeds if age-verified === "true"

​
Email Collection

Shopify integration:
  • Form posts to Shopify’s customer email collection endpoint
  • Emails stored in Shopify admin (Customers section)
  • Can be exported to Klaviyo, Mailchimp, or other email platforms
  • Respects GDPR/privacy regulations (requires consent)
Custom integration:
  • Theme code can be modified for third-party forms (Klaviyo embed, Mailchimp, etc.)
  • Requires code-level customization (not settings-based)

​
Performance

Modal load time:
  • HTML: < 1KB (minimal markup)
  • CSS: ~5-8KB (styling)
  • JavaScript: ~3-5KB (cookie management, timing)
  • Image: 50-300KB (if present)
  • Total: 10-320KB, loads in < 200ms typical
Page impact:
  • Modal renders after page load (no blocking)
  • Delay ensures page content visible first
  • Lightweight JavaScript (no performance hit)

​
Z-Index Hierarchy

Modal overlays are layered:
  1. Age Verification Popup: z-index 1000-1001 (highest)
  2. Newsletter Modal: z-index 999 (below age verification)
  3. Page content: z-index 1-10 (below modals)
Ensures age verification always appears above newsletter modal.

​
Troubleshooting

Modal not appearing on live site:
  • Check “Enable newsletter modal” is checked
  • Test in incognito mode (cookies may remember previous close)
  • Verify delay setting (wait full duration after page load)
  • Check if age verification popup is active (newsletter waits until after age verified)
  • Browser console may show JavaScript errors (check for conflicts)
Modal shows every page:
  • Expected behavior: Modal can appear on each page visit (delay resets per page)
  • Solution: Modal only sets cookie when closed (clicking X or overlay)
  • Workaround: Visitors should close modal once to prevent future displays
Cookie not persisting:
  • Browser privacy settings may block cookies
  • Safari/Firefox may shorten expiration (ITP/ETP)
  • Private/incognito mode deletes cookies on browser close
  • Check browser console for cookie errors
Modal appears too quickly/slowly:
  • Adjust “Add a delay in seconds” setting (1-60 range)
  • Test on live site (Theme Customizer preview may behave differently)
  • Check page load time (delays need time to expire: slow connection = longer effective delay)
Image not displaying:
  • Verify image uploaded successfully in customizer
  • Check file size (keep under 500KB, ideally under 200KB)
  • Try different format (JPG vs PNG)
  • Clear browser cache and hard reload
Text hard to read:
  • Check contrast between background and text colors
  • Use WebAIM Contrast Checker
  • Preview on mobile (smaller screen harder to read)
  • Adjust “Primary Text Color” or “Secondary Text Color”
Layout broken on mobile:
  • Test on actual device (not just browser resize)
  • Image may be too large (compress to under 200KB)
  • Content too long (keep heading < 10 words, body < 3 sentences)
  • Clear theme cache (some themes cache mobile layouts)
Modal conflicts with age verification:
  • Age verification should always show first
  • Newsletter modal should wait until age verified
  • If both appear simultaneously, check theme JavaScript for conflicts
  • Contact theme support if integration broken
Can’t close modal to preview page:
  • Click overlay (outside modal) to close
  • Click any close button (X icon)
  • If stuck, disable “Toggle modal visibility in design mode” in settings
  • Reload Theme Customizer
Form doesn’t submit:
  • Ensure visitor entered valid email
  • Check Shopify admin for customer privacy settings (may block collection)
  • Test on live site (Theme Customizer form may not fully function)
  • Check browser console for form submission errors