> ## Documentation Index
> Fetch the complete documentation index at: https://docs.digifist.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Newsletter Modal

> Popup modal capturing email signups with timed display and cookie-based persistence

## 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

<Steps>
  <Step title="Add the Section">
    Add the Newsletter Modal section to your theme (typically added once globally, not per-page)
  </Step>

  <Step title="Enable the Modal">
    Check "Enable newsletter modal" to activate popup (unchecked hides it site-wide)
  </Step>

  <Step title="Customize Content">
    Set heading ("Enjoy 10% off your first order"), content (signup pitch), and optional image
  </Step>

  <Step title="Configure Timing">
    Set delay (seconds before popup appears) and cookie expiration (days before showing again if closed)
  </Step>
</Steps>

## Settings

<AccordionGroup>
  <Accordion title="Enable Newsletter Modal" icon="toggle-on">
    **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.
  </Accordion>

  <Accordion title="Toggle Modal Visibility in Design Mode" icon="paintbrush">
    **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.
  </Accordion>

  <Accordion title="Add a Delay in Seconds" icon="clock">
    **Type:** Range slider\
    **Range:** 1-60 seconds (step: 1 second)\
    **Default:** 3 seconds

    Controls 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"

    ### Recommended Delays by Goal

    **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.
  </Accordion>

  <Accordion title="Cookie Expiration (Days)" icon="cookie-bite">
    **Type:** Range slider\
    **Range:** 5-365 days (step: 5 days)\
    **Default:** 365 days (1 year)\
    **Info:** "Some devices may restrict the cookie expiration to 7 (seven) days or even 24 hours, for security measures, or this can be even configured by the end user's device. More info [here](https://www.cookiestatus.com/)."

    Controls how long to wait before showing the modal again after a visitor closes it (without subscribing).

    ### How Cookie Expiration Works

    **When visitor closes modal:**

    * Browser cookie created: `_newsletter_modal: none`
    * Cookie stores close date/time
    * Expiration set to specified number of days

    **During expiration period:**

    * Modal won't appear to that visitor
    * Applies across all pages on your site
    * Visitor can browse freely without modal

    **After expiration:**

    * Cookie expires and is deleted
    * Modal appears again on next visit
    * Fresh opportunity to capture signup

    ### Choosing Expiration Duration

    **Short expiration (5-30 days):**

    * **Pro:** More opportunities to convert hesitant visitors
    * **Con:** May annoy frequent visitors who aren't interested
    * **Best for:** Time-sensitive campaigns, fast product launches
    * **Example:** "5 days - see modal again within a week if they don't subscribe"

    **Medium expiration (90-180 days):**

    * **Pro:** Balanced—gives visitors a break but doesn't give up forever
    * **Con:** May miss visitors who reconsider after longer time
    * **Best for:** Seasonal businesses, quarterly product releases
    * **Example:** "90 days - see modal again next season"

    **Long expiration (365 days):** ← **Default**

    * **Pro:** Respects visitor choice for full year, minimal annoyance
    * **Con:** Lost opportunity if visitor would reconsider sooner
    * **Best for:** Evergreen newsletters, general signup campaigns
    * **Example:** "365 days - once a year maximum"

    ### Cookie Restrictions (Important!)

    **Browser/device limitations:**

    * **Safari (iOS/macOS):** Often limits to 7 days maximum (ITP - Intelligent Tracking Prevention)
    * **Firefox:** Can restrict to 24 hours (Enhanced Tracking Protection)
    * **User settings:** Visitors can configure shorter cookie lifespans
    * **Private browsing:** All cookies deleted when browser closed

    **What this means:**

    * Your 365-day setting might become 7 days on Safari
    * Your 30-day setting might become 1 day in strict privacy mode
    * Can't guarantee exact expiration (browser decides final duration)

    **Learn more:** [Cookie Status](https://www.cookiestatus.com/) tracks browser cookie policies

    ### Recommended Durations by Strategy

    **Aggressive growth (maximize signups):**

    * Duration: 5-15 days
    * Rationale: Frequent reminders, multiple chances to convert
    * Risk: Visitor annoyance if too persistent

    **Balanced approach (default):**

    * Duration: 90-180 days
    * Rationale: Re-engage after reasonable time without being pushy
    * Risk: Some browsers will shorten this anyway

    **Respectful branding (minimize annoyance):**

    * Duration: 365 days
    * Rationale: Once a year maximum, respects visitor preference strongly
    * Risk: Miss visitors who'd reconsider sooner

    ### What Happens If Visitor Subscribes

    **Subscription behavior:**

    * Modal typically doesn't set cookie (assumes visitor won't see form again)
    * Some implementations set permanent "subscribed" flag
    * **Mojave behavior:** Check theme code—may still show to subscribers

    **Best practice:** External email provider (Klaviyo, Mailchimp) should hide signup for existing subscribers (requires integration beyond theme).

    **Recommendation:** Use 90-180 days for most use cases (balances growth with respect). Accept that Safari/Firefox may shorten this.
  </Accordion>

  <Accordion title="Background Color" icon="palette">
    **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.
  </Accordion>

  <Accordion title="Primary Text Color" icon="font">
    **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](https://webaim.org/resources/contrastchecker/)

    **Recommendation:** Use black (#000000) for light backgrounds, white (#FFFFFF) for dark backgrounds.
  </Accordion>

  <Accordion title="Secondary Text Color" icon="text">
    **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.
  </Accordion>

  <Accordion title="Flip Image/Content Position" icon="arrows-left-right-to-line">
    **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.
  </Accordion>

  <Accordion title="Heading (Title)" icon="heading">
    **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.
  </Accordion>

  <Accordion title="Content (Entry)" icon="align-left">
    **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."
  </Accordion>

  <Accordion title="Image" icon="image">
    **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.
  </Accordion>
</AccordionGroup>

## Best practices

<CardGroup cols={2}>
  <Card title="Offer Clear Value" icon="gift">
    Lead with specific benefit (10% off, free shipping, exclusive access). Vague "join our newsletter" underperforms concrete offers.
  </Card>

  <Card title="Keep Content Concise" icon="compress">
    1-3 sentences maximum. Visitors won't read paragraphs in a popup. Focus on key benefit and immediate CTA.
  </Card>

  <Card title="Test Delay Timing" icon="stopwatch">
    Start with 3-5 seconds, monitor bounce rate. If visitors leave quickly, increase delay to 10-15 seconds for less intrusive timing.
  </Card>

  <Card title="Respect Cookie Expiration" icon="cookie">
    90-180 days balances growth with respect. Too short (5-10 days) annoys frequent visitors. Remember browsers may shorten your setting.
  </Card>

  <Card title="Ensure High Contrast" icon="circle-half-stroke">
    Background and text colors must have strong contrast. Test on mobile and with accessibility tools—readability is critical to conversion.
  </Card>

  <Card title="Use Quality Images" icon="image">
    If adding image, choose high-quality product or lifestyle photo under 200KB. Compress before uploading to avoid slow modal load.
  </Card>

  <Card title="Mobile-First Preview" icon="mobile">
    70% of traffic is mobile. Preview modal on actual phone—text should be readable, image recognizable, buttons tappable.
  </Card>

  <Card title="A/B Test Offers" icon="vial">
    Test different incentives: 10% off vs free shipping vs exclusive access. Measure signup rate and customer lifetime value.
  </Card>
</CardGroup>

## 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

## Related Sections

* **[Newsletter](/themes/mojave/newsletter)** - Non-modal newsletter signup section (standard page section)
* **[Age Verification Popup](/themes/mojave/age-verification-popup)** - Another modal (age verification takes priority over newsletter)
* **[Footer](/themes/mojave/footer/footer)** - Alternative newsletter signup location (always visible)

## Technical Notes

### Cookie Management

**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](https://webaim.org/resources/contrastchecker/)
* 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