Capture clean pages without newsletter modals, location selectors, surveys, or dimmed backdrops

Remove popups and overlays

Marketing modals, newsletter forms, country selectors, surveys, and age gates can cover the page you intended to capture. AllScreenshots removes these interruptions automatically with the blockPopups option.

blockPopups is enabled by default. It works for regular screenshots, async jobs, bulk and compose captures, scheduled screenshots, website crawls, social images, and stealth captures.

Quick start

The default request already removes supported popups and their dimmed backdrops:

curl -X POST 'https://api.allscreenshots.com/v1/screenshots' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "fullPage": true
  }' \
  --output clean-page.png

You can include the option explicitly when you want the request policy to be self-documenting:

{
  "url": "https://example.com",
  "blockPopups": true
}

What gets removed

The detector looks for interruption intent together with modal-like page structure. It can remove:

newsletter and subscription dialogs
marketing offers and discount modals
country, region, language, and currency selectors
survey prompts
app-install promotions
notification prompts
age-verification gates
related dimmers and backdrops
scroll locks left behind after an overlay is removed

It also watches for interruptions that appear after the initial page load and checks open shadow roots used by web components.

Popup blocking is intentionally conservative. It does not remove every element containing words such as “subscribe” or “country”; the element must also behave like a blocking dialog. Inline newsletter forms and normal page content remain visible.

Choose the right blocking control

Goal	Option
Remove ads and tracking resources	`blockAds`
Remove cookie and privacy consent UI	`blockCookieBanners`
Remove marketing and location interruptions	`blockPopups`
Block third-party domains more aggressively	`blockLevel`
Hide a known element on one site	`hideSelectors`
Apply site-specific visual changes	`customCss`

These controls can be combined:

{
  "url": "https://example.com/product",
  "fullPage": true,
  "blockAds": true,
  "blockCookieBanners": true,
  "blockPopups": true,
  "hideSelectors": ["#chat-widget"]
}

Common workflows

Capture a clean full page

Use stitch mode for pages with lazy-loaded content or sticky elements. Popup cleanup runs again immediately before the output is rendered.

const response = await fetch('https://api.allscreenshots.com/v1/screenshots', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ALLSCREENSHOTS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    fullPage: true,
    fullPageMode: 'stitch',
    waitUntil: 'networkidle',
    blockPopups: true,
  }),
});

if (!response.ok) throw new Error(`Capture failed: ${response.status}`);
const image = await response.blob();

Keep popups for QA or evidence

Set blockPopups to false when the interruption itself is what you need to test or archive:

{
  "url": "https://example.com",
  "blockPopups": false
}

This is useful for newsletter QA, location-routing tests, promotional review, and evidence of the exact user-facing page state.

Clean every page in a crawl

The setting applies to each rendered page discovered by a crawl:

curl -X POST 'https://api.allscreenshots.com/v1/crawls' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "depth": 2,
    "limit": 25,
    "outputs": ["screenshot"],
    "blockPopups": true
  }'

Add a targeted fallback

If a site uses a unique interruption that is deliberately outside the generic detector, add a selector without disabling the default protection:

{
  "url": "https://example.com",
  "blockPopups": true,
  "hideSelectors": ["[data-testid='seasonal-takeover']"]
}

Blocking versus interactive actions

Use popup blocking when you want the underlying page and the interruption can be safely removed. Use interactive actions when the page must be changed through a real interaction—for example, clicking an age gate that controls whether protected content is rendered at all.

{
  "url": "https://example.com",
  "actions": [
    {
      "type": "click",
      "selector": "button[data-action='confirm-age']",
      "optional": true
    }
  ]
}

Troubleshooting

Add a short delay if the site inserts the interruption unusually late.
Use waitFor for a stable piece of real page content.
Add the popup container to hideSelectors.
Use an interactive action if dismissing the dialog changes the page state.

Important content disappeared

Capture the page with blockPopups: false to compare the raw state. If the popup is part of your application rather than a marketing interruption, keep blocking disabled for that workflow and use targeted hideSelectors for unrelated elements.

The page remains dimmed or cannot scroll

The blocker removes related backdrops and restores page scrolling automatically. If a site uses an unusual custom implementation, hide its backdrop alongside the dialog:

{
  "hideSelectors": [".custom-modal", ".custom-modal-backdrop"]
}

Remove popups and overlays

On this page