Fix a popup that breaks on mobile.

Start with viewport containment

The popup’s outer box should remain inside the usable viewport at every supported size. It should not rely on a fixed pixel height copied from desktop, and it should account for mobile browser chrome and safe-area insets.

• Use a viewport-relative maximum height with a safe margin.
• Keep width inside the viewport without negative offsets.
• Prevent merchant content from setting arbitrary outer dimensions.
• Never solve overflow by scaling text below readable sizes.
• Test portrait and landscape orientation.

Separate popup scrolling from body scrolling

When the modal opens, background scrolling is normally locked. The popup’s content region must then remain scrollable. A common failure hides the popup on mobile while leaving the overlay and body lock active, producing a grey page that cannot be used.

1. Open the popup near the top of a long page.
2. Scroll from the heading to the final CTA inside the dialog.
3. Confirm the underlying page does not move.
4. Close the popup.
5. Confirm the original page position is preserved.
6. Confirm body scrolling is restored after close and after an error.

Keep the close control visible and reachable

The close button must not scroll away with long content or sit under a sticky header, browser edge, or image. It needs an accessible name, visible focus, and a touch target of at least 44 by 44 CSS pixels.

Shopify’s theme accessibility guidance also expects modal focus containment, Escape-to-close, return of focus to the launcher, and the dialog role.

Stack side images instead of squeezing two columns

A protected left or right image composition should switch to a top image when its minimum content width is unavailable. The image should use a guarded aspect ratio and crop mode rather than forcing the content column below readable width.

• Reserve image dimensions to avoid layout shift.
• Use cover only when cropping is acceptable.
• Use contain when the full asset must remain visible.
• Keep informative alt text; use empty alt text only for decorative images.
• Test long translations because text expansion can trigger stacking earlier.

Test the whole storefront overlay stack

Mobile corners are shared by many apps. Test PrimePopup together with the Shopify cookie banner, Shopify Inbox or another chat widget, loyalty launchers, sticky add-to-cart controls, announcement bars, and cart drawers.

Test keyboard, zoom, and motion

• Open the dialog using keyboard-only navigation.
• Confirm focus enters the dialog and cannot move into blurred background controls.
• Press Escape and confirm focus returns appropriately.
• Zoom the browser to 200% and verify reflow.
• Enable reduced motion and confirm nonessential animation stops.
• Use a screen reader to confirm the dialog label and description.
• Confirm color is not the only indicator for errors or status.

Minimum mobile test matrix

PrimePopup’s responsive guardrails are designed around these containment and adjustment rules, but the final published theme should always be tested with the merchant’s actual app stack.