After opening a mini program popup, swiping a finger on the gray mask still moves the list behind it—what isn't blocking it?

Conclusion first: When a mini program popup is open, the background still scrolls along with it. In most cases, it's not that the mask layer didn't cover it; rather, the mask only blocks clicks and does not stop touch swipe gestures. Once a finger swipes, the scroll is passed to the page underneath the popup. In 2026, a common approach is: lock the underlying page scroll when the popup opens, and restore the scroll position after it closes. Judging whether it passes is simple—press a finger on the mask and swipe up and down; the background page should not move.

When the popup is open and the background still scrolls, where does the problem usually come from?

The mini program page itself is a full-page scrolling container, and the popup is usually positioned with fixed on top. The mask can receive click events, but it may not receive and prevent swipe events. When the popup content itself is not long enough and has no scrolling area of its own, a finger swiping on the mask causes the event to bubble up to the page layer, and the page scrolls along. This is what is commonly called scroll penetration.

The direct consequence is: the user only wanted to close the popup, but ended up swiping away the background content; after returning, they find the list position has changed and have to search again. According to enterprise project delivery habits, overlays such as popups, drawers, and bottom pickers all need their swipe behavior checked separately, not just whether they can be tapped.

• The mask only has a background color and z-index set, and does not intercept touchmove events;
• The popup content is not scrollable, for example it only has a confirm button, and the finger lands on an empty area of the mask;
• The underlying page is very long, so one swipe can move several hundred pixels, making the problem look more obvious;
• It only appears on some device models, because Android and iOS differ in touch gesture handling.

First distinguish whether it is scroll penetration or the popup itself was written incorrectly

Don't rush to change the code. Use the three-check method to clarify the phenomenon: check the gesture touch point, check the popup content, and check the underlying scroll container. Once clarified, you still change the same place, but troubleshooting time can usually shrink from most of a day to around half an hour, which is an experience range.

1. Check the gesture touch point: press a finger on an empty area of the mask and swipe, and see whether the background moves; then press on the popup card and swipe, and see whether it is the same. If the two behave differently, the problem is at the mask layer.
2. Check the popup content: if the popup contains a long list or terms text and needs to scroll itself, determine whether the popup scrolls normally while the background also scrolls, or the popup does not scroll at all.
3. Check the underlying container: confirm whether page scrolling is at the page layer or inside a scroll-view. Scroll penetration in a scroll-view behaves differently from full-page scrolling, and the way to lock it is also different.

The acceptable criteria are: while the popup is open, the background page position stays fixed; after the popup closes, the page stays at the position it was at before opening, rather than jumping back to the top.

Several scroll-locking approaches and when each is suitable

No single implementation works for every page. According to 2026 project delivery habits, common approaches can be grouped into three categories, and the choice depends on the complexity of the page structure and the maintenance cost you are willing to take on.

• Option A: The mask layer intercepts swipe events. Add catchtouchmove to the mask to stop the event from propagating downward. The change is small and quick to implement, suitable for scenarios where the popup content does not need to scroll and the page structure is simple; the downside is that if the popup has scrollable content, it must be released separately, otherwise the popup itself cannot scroll.
• Option B: Lock the page when the popup opens. When the popup opens, add fixed positioning to the underlying page, record the current scroll position, and restore it when the popup closes. Suitable for pages where the underlying content is a long list and needs to be strictly locked; the cost is handling position restoration. If done poorly, closing the popup jumps to the top, and rework is usually 1–2 rounds, which is an experience range.
• Option C: Handle it uniformly with an overlay component. Some mini program base libraries provide overlay components with built-in masks and scroll locking; specific capabilities are subject to the official documentation. Suitable for projects with many popup types that want a unified solution; pay attention to base library version compatibility and custom style space.

If there are multiple pages and multiple popups, it is advisable not to hand-write it in each place, but to encapsulate it into a unified component. The standard for judging whether the encapsulation is acceptable is: when a new page integrates it, it only fills in content and no longer needs to care about scroll locking.

From a verifiable comparison, Option A's change volume is commonly a few lines to one or two places; Option B requires extra handling for position recording and restoration; Option C has a higher upfront encapsulation cost, but the integration cost for each additional popup later is much lower. According to project experience ranges, when the number of popups is within three, A or B is often sufficient; when there are more than five and they are spread across multiple pages, unified encapsulation usually has lower long-term maintenance cost.

Applicable scenarios and boundaries

Scroll penetration is worth handling specifically, but not every popup needs the full solution. The criteria are: whether there is scrollable content underneath the popup, and whether users will swipe on the mask.

• Worth handling: bottom drawers, filter panels, address selection, date selection, half-screen explanation pages, and popups on pages with long lists.
• Can be simplified: short pages with only two or three screens of content, where the popup basically does not need swiping once it appears; purely informational overlays, since many platform components already include masks and locking capabilities.
• Not necessary: pages that navigate to a full page, and scenarios where the popup already covers the full screen when open and there is no scrollable content underneath.
• Common pitfalls: locking the popup but forgetting to restore, the lock being released early when multiple popups stack, and the page jumping back to the top after the popup closes.

Where delivery often gets stuck

A common situation in projects is: budgets and schedules are tight, popups are accepted only by whether they can pop up and close, and swipe behavior is not on the acceptance checklist; then during a real-device demo for the client, one swipe sends the background moving, the client raises it on the spot, and developers have to go back and fix it, usually costing an extra 0.5–1 day of rework, which is an experience range. In practice, a steadier approach is to list popups, drawers, and pickers as an overlay verification checklist before testing handoff, and swipe through each one on real Android and iOS devices before submitting. The trade-off is that testing time increases somewhat; a typical range is a few minutes to ten-plus minutes per overlay, but it reduces post-launch rework.

Some teams leave this work to developer self-testing, with product only clicking through once at the end, and as a result, popups with few buttons and short content get missed. A steadier division of labor is: developers are responsible for scroll locking and position restoration, testers are responsible for swiping once on the mask and once on the content area on real devices, and both sides confirm before merging. In mobile custom delivery, Xiyue Company also puts this kind of interaction detail into self-test items, rather than waiting for the client to find it.

FAQ

When the popup is open, the background still scrolls—is it because the mask opacity or color is set wrong?

Usually not. The mask color only affects visual covering and cannot stop touch swipes; the problem is that the swipe event is not prevented, or the underlying page is not locked.

iOS has no problem, but on Android the background scrolls—do I need to write two separate sets of logic?

In most cases, you do not need two sets of logic. Once the underlying scroll is locked in a unified way, both platforms usually behave consistently; however, it is still recommended to regression-test on real Android and iOS devices separately.

After locking scrolling, closing the popup makes the page jump to the top—can that be fixed?

Yes. A common approach is to record the current scroll position before locking, and restore it when the popup closes; handle this in a unified component instead of writing it in every page.

If the popup content is very long and needs to scroll itself, will it conflict with locking the scroll?

It can. The usual approach is to intercept swipes only on the mask, while the popup content area keeps its own scroll ability, handling the two separately; during testing, swipe both areas.

If every popup has to be handled separately, will the workload be too large?

When there are few popups, you can handle them one by one; when there are more than three to five and many pages, encapsulating them into a unified overlay component is easier and lowers later maintenance cost.

If your mini program already has popups, drawers, or bottom pickers, it is recommended to swipe through each one on real Android and iOS devices first, list the scenarios where scrolling leaks through, and then decide whether to fix them one by one or encapsulate them uniformly; for projects with very short pages and little scrollable content underneath popups, you can leave it for now. If unsure, check the base library support and component capabilities against the official documentation before making changes.