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

# Age Verification Popup

> Modal popup requiring age confirmation before site access

## What It Does

The **Age Verification Popup** displays a full-screen modal overlay requiring visitors to confirm their age before accessing your storefront. Essential for stores selling age-restricted products like alcohol, tobacco, CBD, or adult content, this popup ensures compliance with age restrictions while maintaining a professional user experience.

Visitors who confirm their age can proceed to browse, while those who decline are redirected to another URL. The popup appears once per browser session—after confirmation, the visitor won't see it again until they close their browser or clear cookies.

## Getting Started

<Steps>
  <Step title="Add the Section">
    Add the Age Verification Popup section to your theme (typically added once in theme settings, not per-page)
  </Step>

  <Step title="Configure Message">
    Set your heading ("Verify your age") and verification message explaining your age requirements
  </Step>

  <Step title="Set Button Labels & Decline URL">
    Customize button text ("Yes"/"No" or "I'm 21+"/"Under 21") and set where declined visitors go (homepage, exit page, or external URL)
  </Step>

  <Step title="Optional Background Image">
    Upload a background image to enhance the popup's visual appearance (optional but recommended for brand consistency)
  </Step>
</Steps>

## Settings

<AccordionGroup>
  <Accordion title="Image" icon="image">
    **Type:** Image picker\
    **Default:** Empty (no image)

    Upload a background image displayed behind the verification content.

    ### Image Purpose

    The background image enhances visual appeal and reinforces brand identity:

    * **Product photography:** Show your products (wine bottles, craft beer, luxury items)
    * **Brand lifestyle:** Lifestyle imagery that reflects your brand values
    * **Abstract/texture:** Subtle patterns or textures for minimal distraction
    * **Logo/branding:** Large logo or brand mark for recognition

    ### Image Specifications

    **Recommended size:** 800x1200px to 1200x1600px (portrait orientation)

    * **Aspect ratio:** 2:3 or 3:4 works well for mobile-first display
    * **File format:** JPG (photographs), PNG (graphics with transparency)
    * **File size:** Under 300KB for fast loading (visitors must wait for popup to load)
    * **Content safe area:** Keep important content centered—text overlays on top

    ### Without Image

    If no image uploaded:

    * Popup displays content on solid background color (from theme settings)
    * Simpler, faster-loading popup
    * More focus on text message

    **Recommendation:** Use image for premium/lifestyle brands, skip for minimal/functional stores.
  </Accordion>

  <Accordion title="Heading" icon="heading">
    **Type:** Inline rich text\
    **Default:** "Verify your age"

    Main heading displayed at top of popup. Brief, direct, and clear about the requirement.

    ### Heading Examples

    **Standard age verification:**

    * "Verify your age"
    * "Age verification required"
    * "Confirm your age"

    **Specific age requirements:**

    * "Are you 21 or older?"
    * "Must be 18+ to enter"
    * "21+ only"

    **Brand-friendly:**

    * "Welcome! Let's verify your age"
    * "Age check"
    * "Please confirm you're of legal age"

    ### Best Practices

    **Keep it short:** 2-5 words ideal (scans quickly on mobile)
    **Be direct:** Clear about what's being asked
    **Match your tone:** Professional for alcohol/tobacco, friendlier for other products
    **Include age if specific:** "21+" more specific than "of age"

    ### Rich Text Formatting

    Supports bold and italic:

    * **Bold:** "Verify **your** age" (emphasis)
    * *Italic:* Less common, use sparingly

    **Recommendation:** Keep unformatted for maximum clarity and readability.
  </Accordion>

  <Accordion title="Subheading (Text)" icon="align-left">
    **Type:** Rich text (multiple paragraphs supported)\
    **Default:** "You must be 18 years of age or older to enter this site. Please verify your age."

    Detailed verification message explaining age requirements. Supports multiple paragraphs and formatting.

    ### Message Components

    A complete verification message typically includes:

    1. **Age requirement:** Specific age threshold (18, 19, 21 depending on jurisdiction)
    2. **Reason:** What's being protected (site access, product purchase)
    3. **Action:** What visitor needs to do (confirm, verify)

    ### Message Examples

    **Alcohol (US - 21+):**
    "You must be 21 years of age or older to purchase alcohol. By entering this site, you agree to our terms of use and privacy policy."

    **Alcohol (International - 18+):**
    "This website sells alcoholic beverages. You must be 18 or older to access this content. Please verify your age to continue."

    **CBD products:**
    "Our CBD products are intended for adults 21 and over. By clicking 'Yes,' you confirm you meet the legal age requirement in your jurisdiction."

    **Adult content:**
    "This site contains mature content. You must be 18+ to enter. By confirming, you acknowledge you are of legal age in your location."

    **Multiple jurisdictions:**
    "You must meet the legal drinking age in your country to enter this site. Legal age varies by jurisdiction (18-21 years). Please verify your age."

    ### Legal Considerations

    **Include:**

    * Specific age (18, 21, etc.)
    * Reference to jurisdiction ("in your state," "in your country")
    * Action being confirmed ("access site," "purchase products")

    **Consider adding:**

    * Link to terms of use or privacy policy
    * Reference to local laws
    * Disclaimer about self-attestation

    ### Rich Text Formatting

    **Bold for emphasis:**
    "You must be **21 years of age or older** to enter this site."

    **Multiple paragraphs:**

    ```
    You must be 21 or older to purchase alcohol.

    By entering, you agree to our Terms of Service.
    ```

    **Links (if needed):**
    "Read our [Terms of Service](/policies/terms-of-service) for more information."

    **Keep readable:** 2-3 sentences max. Too much text reduces compliance.
  </Accordion>

  <Accordion title="Confirmation Button Label" icon="check">
    **Type:** Text\
    **Default:** "Yes"

    Label for the button visitors click to confirm they meet age requirements and proceed to site.

    ### Button Label Options

    **Simple confirmation:**

    * "Yes" (default, clear and direct)
    * "Enter"
    * "Confirm"
    * "I agree"

    **Specific age confirmation:**

    * "I'm 21+"
    * "I'm 18 or older"
    * "Yes, I'm of legal age"
    * "21+ Enter site"

    **Action-oriented:**

    * "Enter site"
    * "Continue"
    * "Proceed"
    * "Shop now"

    ### Best Practices

    **Keep short:** 1-3 words (button space is limited)
    **Be clear:** No ambiguity about what action does
    **Match heading:** If heading asks "Are you 21+?", button should be "Yes" or "I'm 21+"
    **Positive action:** Confirming should feel straightforward, not tricky

    **Avoid:**

    * "No" (confusing—negative answer to positive action)
    * Long phrases ("Yes, I confirm I am 21 years old")
    * Vague terms ("Maybe," "Not sure")

    **Recommendation:** Stick with "Yes" or specify age ("I'm 21+") for maximum clarity.
  </Accordion>

  <Accordion title="Decline Button Label" icon="xmark">
    **Type:** Text\
    **Default:** "No"

    Label for the button visitors click if they don't meet age requirements or wish to decline entry.

    ### Button Label Options

    **Simple decline:**

    * "No" (default, clear opposite of "Yes")
    * "Exit"
    * "Leave"
    * "Cancel"

    **Specific age decline:**

    * "I'm under 21"
    * "Under 18"
    * "Not of age"

    **Action-oriented:**

    * "Exit site"
    * "Go back"
    * "Leave site"

    ### Best Practices

    **Mirror confirmation button:** If confirm is "Yes," decline should be "No"
    **Clear consequence:** Label should indicate action (leaving site)
    **Short:** 1-2 words preferred
    **No guilt:** Avoid judgmental language ("I'm too young," "I don't belong here")

    **Pairing examples:**

    * Confirm "Yes" → Decline "No"
    * Confirm "I'm 21+" → Decline "Under 21"
    * Confirm "Enter" → Decline "Exit"
    * Confirm "Continue" → Decline "Leave"

    **Recommendation:** Use "No" (matches default "Yes") or "Exit" (action-focused).
  </Accordion>

  <Accordion title="Decline Button URL" icon="link">
    **Type:** URL\
    **Default:** "/" (homepage)

    Where visitors are redirected if they click the decline button.

    ### URL Options

    **Redirect to homepage:**

    * **URL:** `/`
    * **Reason:** Default option, sends declined visitors to your homepage
    * **Use when:** You want to keep declined visitors in ecosystem but away from age-restricted content
    * **Note:** Only works if homepage itself doesn't require age verification

    **Redirect to external site:**

    * **URL:** `https://www.google.com` or similar
    * **Reason:** Sends declined visitors away from your site entirely
    * **Use when:** Site exclusively sells age-restricted products (entire site requires verification)
    * **Common choices:** Google, educational resource about age restrictions

    **Redirect to specific page:**

    * **URL:** `/pages/underage` or `/pages/age-restricted`
    * **Reason:** Custom page explaining age policy
    * **Use when:** You want to provide more information to declined visitors
    * **Content ideas:** Explanation of policy, contact info, appeal process

    **Redirect to info page:**

    * **URL:** `/pages/alcohol-policy`
    * **Reason:** Educational page about your products and age restrictions
    * **Use when:** Building trust around compliance

    ### Best Practices

    **Consider your business model:**

    * **Entire site age-restricted** (alcohol-only store): External redirect (Google)
    * **Mixed products** (some age-restricted, some not): Homepage redirect
    * **Want to educate:** Custom informational page

    **Legal compliance:**

    * Check if your jurisdiction requires specific decline destination
    * Some regions may require visitors to exit site entirely

    **User experience:**

    * **External redirects feel harsh** but are appropriate for fully restricted sites
    * **Homepage redirects feel friendlier** but only work if homepage accessible
    * **Info pages build trust** but require creating additional content

    **Testing:** Make sure decline URL is live and accessible (broken URL creates bad experience).

    **Recommendation:** Use `/` (homepage) for mixed stores, external URL (Google) for age-restricted-only stores.
  </Accordion>

  <Accordion title="Show Popup on Customizer" icon="eye">
    **Type:** Checkbox\
    **Default:** Unchecked (hidden in customizer)

    Controls whether the popup displays when you're editing the theme in the Shopify customizer.

    ### When to Enable

    **Enable (check) when:**

    * You're actively editing popup content or styling
    * You want to preview popup appearance immediately
    * You need to test popup layout with different content
    * You're setting up popup for the first time

    **Disable (uncheck) when:**

    * You're editing other sections (popup blocks view)
    * You've finished customizing popup
    * You're working on navigation or other theme elements that popup would obscure
    * You want to see page layout without popup interference

    ### How It Works

    **Enabled (checked):**

    * Popup displays immediately when you open Theme Customizer
    * Popup refreshes/updates when you change settings
    * You can see live preview of changes
    * Blocks view of other sections

    **Disabled (unchecked):**

    * Popup hidden in editor (but still shows on live site)
    * You can edit other sections without popup in the way
    * Popup settings still accessible in section list

    ### Best Practice Workflow

    1. **Enable** popup visibility in customizer
    2. Edit content, colors, image, buttons
    3. Preview and refine appearance
    4. **Disable** popup visibility when done
    5. Continue editing other sections
    6. Test popup on live site (preview theme in new tab, use incognito mode)

    **Important:** This setting only affects Theme Customizer visibility. Live site always shows popup to unverified visitors regardless of this setting.

    **Recommendation:** Enable only while actively editing popup, disable after to avoid blocking other work.
  </Accordion>
</AccordionGroup>

## Best practices

<CardGroup cols={2}>
  <Card title="Clear Age Requirement" icon="calendar">
    Specify exact age (18, 21, etc.) in your message. Generic "of age" creates confusion across jurisdictions with different legal ages.
  </Card>

  <Card title="Test Decline Destination" icon="arrow-right-from-bracket">
    Verify your decline URL works and leads to appropriate page. Broken link creates poor experience and potential compliance issues.
  </Card>

  <Card title="Use Background Image" icon="image">
    Background image enhances professionalism and brand recognition. Choose image that reflects your products without distracting from message.
  </Card>

  <Card title="Keep Message Concise" icon="compress">
    2-3 sentences maximum. Visitors won't read lengthy legal text. Focus on: age requirement, what's being verified, confirmation action.
  </Card>

  <Card title="Match Button Labels" icon="arrows-left-right">
    Confirm/decline buttons should mirror each other logically. "Yes"/"No", "Enter"/"Exit", "I'm 21+"/"Under 21". Avoid mismatched pairs.
  </Card>

  <Card title="Consider Legal Requirements" icon="scale-balanced">
    Consult legal counsel about age verification requirements in your jurisdiction. Popup provides basic gate but may not satisfy all regulations.
  </Card>

  <Card title="Test in Incognito Mode" icon="user-secret">
    Test popup behavior in private/incognito browser window to simulate first-time visitor experience. Check appearance, message clarity, buttons.
  </Card>

  <Card title="Mobile-First Design" icon="mobile">
    Preview popup on mobile devices. Ensure text readable, buttons tappable, image doesn't obscure message. Most visitors use mobile.
  </Card>
</CardGroup>

## Common Use Cases

### Alcohol Store (US, 21+)

**Message:** "You must be 21 years of age or older to purchase alcohol. By entering, you agree to our Terms of Service."

**Buttons:** "I'm 21+" (confirm), "Under 21" (decline)

**Decline URL:** `https://www.google.com` (external redirect since entire store is age-restricted)

**Image:** Product photography of wine/beer bottles, or lifestyle image of social gathering

**Best for:** Dedicated alcohol retailers, wine shops, breweries

### CBD/Hemp Products (21+)

**Message:** "Our CBD products are for adults 21 and over. By clicking 'Enter,' you confirm you meet the legal age requirement in your jurisdiction."

**Buttons:** "Enter" (confirm), "Exit" (decline)

**Decline URL:** `/pages/cbd-policy` (info page explaining regulations)

**Image:** Hemp leaf imagery, product photography, or natural/botanical visuals

**Best for:** CBD stores, wellness shops, dispensaries

### Tobacco/Vaping (18+)

**Message:** "This website sells tobacco and vaping products. You must be 18 or older to access this site. Please verify your age."

**Buttons:** "Yes, I'm 18+" (confirm), "No, I'm under 18" (decline)

**Decline URL:** `https://www.cdc.gov/tobacco/` (educational resource)

**Image:** Product photography (vapes, accessories), abstract smoke textures

**Best for:** Vape shops, tobacco retailers

### Adult Content or Mature Products (18+)

**Message:** "This site contains mature content intended for adults. You must be 18 years or older to enter. By confirming, you acknowledge you are of legal age."

**Buttons:** "I'm 18+" (confirm), "Under 18" (decline)

**Decline URL:** `/` (homepage redirect, or external if site is entirely adult-oriented)

**Image:** Subtle, tasteful imagery that conveys maturity without explicit content

**Best for:** Adult novelty stores, mature gaming, collectibles with adult themes

### International Store (Variable Ages)

**Message:** "This site sells age-restricted products. You must meet the legal age in your country to enter (typically 18-21 years). Please confirm your age."

**Buttons:** "Confirm" (confirm), "Cancel" (decline)

**Decline URL:** `/pages/age-policy` (page explaining international age variations)

**Image:** Global/international imagery, or neutral product photos

**Best for:** International retailers with customers across multiple jurisdictions

### Luxury/High-Value Items (Not Age-Restricted, but Exclusive)

**Message:** "Welcome to our exclusive collection. Please confirm you wish to explore our luxury offerings."

**Buttons:** "Enter" (confirm), "Not interested" (decline)

**Decline URL:** `/` (homepage)

**Image:** Luxury product photography, elegant lifestyle imagery

**Best for:** High-end retailers using popup for exclusivity rather than age verification (note: not for legal compliance)

## Layout Behavior

### Desktop Layout

The popup displays centered on screen:

* **Full viewport overlay:** Dark semi-transparent background covers entire page
* **Popup dimensions:** Approximately 750px max width, auto height
* **Content layout:** Two-column layout on desktop (if image present)
  * **Left (30%):** Background image
  * **Right (70%):** Content (heading, message, buttons)
* **No image:** Content centered with padding

### Mobile Layout

Optimized for mobile screens:

* **Full screen:** Popup occupies full viewport height
* **Single column:** Image (if present) stacked above content
* **Image height:** \~16rem (160px) fixed height on mobile
* **Content:** Full-width below image
* **Buttons:** Full-width stacked (confirm above decline), \~2.4rem gap between buttons
* **Scrollable:** Content scrolls if message is lengthy

### Visual Effects

**Entrance animation:**

* Desktop: Fade + scale from 0 to 100%
* Mobile: Slide up from bottom of screen
* Duration: \~300ms

**Background overlay:**

* Semi-transparent black (50% opacity)
* Blurs page content behind popup (subtle \~1.2rem blur)
* Prevents interaction with page until verified

## Related Sections

* **[Newsletter Modal](/themes/mojave/newsletter-modal)** - Another modal popup (newsletter signup)
* **[Header](/themes/mojave/header/header)** - Navigation that appears after age verification
* **[Footer](/themes/mojave/footer/footer)** - Legal links (Terms, Privacy) often referenced in age verification

## Technical Notes

### Session Storage & Cookies

The popup uses browser **session storage** to remember verification:

**On confirmation:**

* Sets `age-verified: true` in session storage
* Popup won't show again during current browser session
* Session ends when user closes browser (all tabs)

**Cookie expiration:**

* No persistent cookies created (unlike Newsletter Modal)
* Each new browser session requires re-verification
* Private/incognito mode always shows popup

**Across devices:**

* Verification is per-browser, per-device
* User on phone must verify separately from desktop
* Not tied to customer account

### Interaction Blocking

When popup is open:

* **Page content unclickable:** All links, buttons below popup disabled
* **Pointer events blocked:** CSS `pointer-events: none` on body
* **Scroll locked:** Page scroll disabled on some implementations
* **Keyboard focus trapped:** Tab key cycles through popup elements only

### Priority Over Other Popups

Age verification takes priority:

* **Newsletter popup:** If both age verification and newsletter modal active, age verification shows first
* **Only after verification:** Newsletter modal appears (if configured with delay)
* **JavaScript coordination:** Newsletter modal checks for `age-verified` flag before displaying

### Performance

**Popup loading:**

* HTML renders immediately (no JavaScript delay)
* Background image lazy loads (doesn't block popup appearance)
* Minimal CSS (\~5KB)
* Total load time: \< 100ms typical

**Page blocking:**

* Body `pointer-events: none` until verification
* Ensures popup can't be bypassed by clicking behind it
* Re-enables after confirmation

### Design Mode Behavior

**In theme customizer:**

* Popup only shows if "Show popup on customizer" enabled
* Otherwise hidden but section accessible in editor sidebar
* Preview changes live when customizer toggle enabled

**On live site:**

* Always shows to unverified visitors
* Ignores customizer toggle setting
* Session storage determines visibility

## Troubleshooting

**Popup not appearing on live site:**

* Check if you've already verified age in current browser session
* Test in incognito/private browsing mode (fresh session)
* Verify section is enabled in theme customizer
* Check browser console for JavaScript errors

**Popup shows every page load:**

* Session storage may be disabled in browser settings
* Privacy mode / incognito resets session on each tab
* Browser extension may be blocking session storage
* Expected behavior: User should verify once per session

**Decline button doesn't work:**

* Verify "Decline Button URL" is valid (not empty)
* Check for typos in URL field
* Test decline destination URL directly (paste in browser)
* Ensure URL is relative (`/page`) or full (`https://...`)

**Background image not displaying:**

* Confirm image uploaded successfully in customizer
* Check image file size (keep under 500KB)
* Try different image format (JPG vs PNG)
* Verify image isn't corrupted (open directly)

**Buttons overlap or layout broken:**

* Test on actual mobile device (not just browser resize)
* Check message length (very long text can break layout)
* Ensure button labels are short (1-3 words)
* Clear browser cache and hard reload

**Can't edit other sections in customizer:**

* Disable "Show popup on customizer" checkbox
* Popup blocks view when enabled in editor
* After disabling, popup hidden in editor but still editable in section list

**Popup appears behind other content:**

* Check for theme CSS conflicts (high z-index on other elements)
* Age verification should have z-index 1000+
* Contact theme support if popup is consistently overlaid

**Text hard to read over image:**

* Choose image with darker/lighter area for text
* Consider adding semi-transparent overlay (theme-level customization)
* Test on mobile where text area is smaller
* Alternatively, remove image and use solid background