Tutorial

How to Screenshot Dynamic Pages: SPAs, Lazy Loading and Animations

Wait strategies for SPAs, lazy images, charts and animations: which Screenshotly controls to use, the order they run in, plan requirements and known limits.

Asad AliDecember 10, 202510 min read

A screenshot of a modern web page is a race. The HTML arrives, JavaScript hydrates the app, data requests return, images load as they scroll into view, and animations play. If the capture fires too early, you get a spinner, a grey placeholder, or a chart caught halfway through its entrance animation.

This guide covers the Screenshotly controls that decide when the capture happens and what state the page is in. It also covers the order those controls run in and the cases they can't fix. Every request body below was validated against the API's request schema on 13 November 2026.

If you're choosing a viewport size rather than timing, see How to Choose a Screenshot Viewport.

Quick decision table

Symptom in the capture Control to try first Plan
Loading spinner or empty app shell waitForSelector on an element that only exists after data loads All plans
Some data panels still loading waitForNetworkIdle: true All plans
Grey boxes where images should be (below the fold) scroll or a javascript scroll loop Growth+
Elements caught mid-fade or mid-slide javascript that freezes animations, or a short delay Growth+ / all plans
Chart axes drawn but bars missing App-set ready marker plus waitForSelector All plans
Cookie banner or chat bubble covering content blockAds, hideSelectors or aiRemoval All plans / Growth+ / Growth+
Menu, tab or modal needs to be open javascript that clicks it Growth+
Not sure what the page looked like at capture time format: "html" to get the DOM as rendered Basic+

How Screenshotly decides when to capture

Each request goes through these steps in a fixed order. Knowing the order explains most "why didn't my wait work?" problems.

  1. Navigate. The browser loads url and waits for DOMContentLoaded. With waitForNetworkIdle: true it waits instead until the network has gone quiet (Puppeteer's networkidle0). Navigation times out after 30 seconds.
  2. Ad-blocking CSS is injected if blockAds is true.
  3. waitForSelector waits up to 10 seconds for the selector. If it never appears, the request carries on.
  4. javascript runs in the page. If it returns a promise, Screenshotly waits for it, then pauses about 300 ms.
  5. delay waits a fixed number of milliseconds (maximum 10,000).
  6. hideSelectors are hidden with injected CSS.
  7. aiRemoval hides detected overlays.
  8. scroll scrolls the page by distance pixels at speed pixels per second, returns to the top and waits about 500 ms.
  9. Capture. The viewport, the full page, a clip rectangle or a selector element is captured.

Two consequences matter in practice:

  • delay runs after your javascript. That makes it a good settling buffer for work your script started.
  • scroll runs last, after delay. Images it triggers get only the built-in half-second before the capture. If they need longer, scroll from javascript instead, so the delay runs afterwards.

Wait strategies

Wait for a known element

This is the most precise control. Pick an element that exists only once the content you care about has rendered.

{
  "url": "https://app.example.com/reports/42",
  "waitForSelector": "[data-testid=\"report-table\"] tbody tr",
  "format": "png"
}

Waiting for .app or #root doesn't help, because those exist in the initial HTML. Wait for something your data fills in, such as a table row, a chart's SVG path or a heading that contains data.

Remember that a missing selector doesn't fail the request. After 10 seconds the capture happens anyway. Check a few outputs by eye when you first set this up.

Wait for the network to go quiet

waitForNetworkIdle: true helps when a page renders the shell first and then fetches data from APIs.

{
  "url": "https://example.com/pricing",
  "waitForNetworkIdle": true,
  "format": "png"
}

It has a limit. Pages that keep polling, stream analytics beacons or long-poll an endpoint may never go idle. The navigation then hits its 30-second timeout and the request fails. If that happens, switch back to the default and use waitForSelector.

Fixed delay

delay is the blunt tool. It works when you can't change the page and nothing in the DOM signals readiness, but it's always either too short on a slow day or too long on a fast one.

{
  "url": "https://example.com",
  "waitForSelector": "main h1",
  "delay": 1500,
  "format": "png"
}

Use it as a small buffer on top of a selector wait, not as the only wait.

Let the app say when it's ready

If you control the page, this is the most dependable pattern. Have the app set an attribute once data has arrived and charts have drawn:

// In your app, after data and charts have rendered
export function markScreenshotReady() {
  document.documentElement.dataset.screenshotReady = 'true';
}

Then wait for it:

{
  "url": "https://dashboard.example.com/weekly",
  "waitForSelector": "[data-screenshot-ready=\"true\"]",
  "format": "png"
}

With Chart.js, for example, call markScreenshotReady() from the chart's animation.onComplete callback, or turn chart animation off for screenshot views. Either way, the capture waits for the final frame rather than guessing.

If you need the request to fail when the page never becomes ready, capture an element instead. With selector, a missing element returns a 400 error rather than a picture of a spinner:

{
  "url": "https://dashboard.example.com/weekly",
  "waitForSelector": "[data-screenshot-ready=\"true\"]",
  "selector": "[data-screenshot-ready=\"true\"] main",
  "format": "png"
}

Single-page apps

You don't need special handling for client-side routing. Pass the deep link (https://app.example.com/settings/billing or https://app.example.com/#/settings) and the app's router renders that view on load. Then wait for that view's content with waitForSelector.

For pages behind a login, see the authenticated screenshot guide. Cookies and headers need the Basic plan or above.

Lazy-loaded images

Images with loading="lazy" or an IntersectionObserver loader only load near the viewport. A viewport capture of the top of the page is usually fine. A full-page capture is where it goes wrong: fullPage: true captures the whole document without scrolling it, so images further down can still be placeholders.

Option 1: the scroll option (Growth+)

{
  "url": "https://shop.example.com/collections/new",
  "fullPage": true,
  "scroll": { "enabled": true, "distance": 6000, "speed": 1500 },
  "format": "jpeg",
  "quality": 85
}

distance is 100–50,000 px and speed is 100–5,000 px per second. Keep distance / speed short. The example spends about 4 seconds scrolling, on top of navigation and your other waits.

Option 2: scroll from javascript, then delay (Growth+)

Because delay runs after javascript, this variant gives images time to finish decoding:

{
  "url": "https://shop.example.com/collections/new",
  "fullPage": true,
  "javascript": "(async () => { const step = window.innerHeight; for (let y = 0; y < document.body.scrollHeight && y < 20000; y += step) { window.scrollTo(0, y); await new Promise(r => setTimeout(r, 250)); } window.scrollTo(0, 0); })()",
  "delay": 1000,
  "format": "jpeg",
  "quality": 85
}

The y < 20000 guard stops the loop on pages that keep growing as you scroll.

Option 3: switch images to eager loading (Growth+)

If the page uses native lazy loading, you can turn it off before the capture:

{
  "url": "https://blog.example.com/long-post",
  "fullPage": true,
  "javascript": "(async () => { document.querySelectorAll('img[loading=\"lazy\"]').forEach(img => { img.loading = 'eager'; }); await new Promise(r => setTimeout(r, 1500)); })()",
  "format": "png"
}

Libraries that keep the real URL in data-src need their own swap, such as img.src = img.dataset.src. Check how your page does it.

Animations and transitions

Entrance animations, carousels and skeleton shimmer can all leave elements half-drawn. You have two choices.

Wait them out. If the animation runs once and is short, a delay slightly longer than it is enough.

Freeze them (Growth+). This snippet sets CSS animation and transition durations to zero and jumps any running Web Animations to their end:

{
  "url": "https://example.com",
  "javascript": "(async () => { const s = document.createElement('style'); s.textContent = '*, *::before, *::after { animation-duration: 0s !important; animation-delay: 0s !important; transition-duration: 0s !important; transition-delay: 0s !important; caret-color: transparent !important; }'; document.head.appendChild(s); for (const a of document.getAnimations()) { try { a.finish(); } catch (e) {} } })()",
  "format": "png"
}

A caveat: an element only stays in its end state if its animation uses animation-fill-mode: forwards (or both). Otherwise it goes back to its base styles. If a fade-in element's base style is opacity: 0, it will be invisible after freezing. Look at the first capture and adjust.

Infinite animations, such as spinners, can't be finished. The try block skips them, and the zero duration stops them moving.

Charts, maps and canvas

  • SVG charts (D3, Recharts, Highcharts SVG mode): wait for a specific drawn element, such as svg .bar or svg path.line, not just the <svg> container.
  • Canvas charts (Chart.js, ECharts canvas mode): the DOM doesn't change when drawing finishes, so selector waits can't see it. Use the app-set ready marker, or turn animation off on screenshot views.
  • Maps and WebGL: tiles and 3D scenes draw on their own schedule, and WebGL support in a headless server browser isn't something to assume. Test your specific map before you build a pipeline around it, and prefer a static map image on screenshot views where you can.

To capture a state the user reaches by clicking, click it from javascript:

{
  "url": "https://example.com/pricing",
  "javascript": "(async () => { document.querySelector('[data-tab=\"annual\"]')?.click(); await new Promise(r => setTimeout(r, 400)); })()",
  "format": "png"
}

Hover states are the exception. Dispatching mouseenter from a script runs your event listeners, but it doesn't make CSS :hover rules match. If a hover style matters, add a class that applies the same styles and set it from the script.

Overlays

Cookie banners and chat widgets often appear after a timer, so they turn up in captures of otherwise-ready pages.

  • blockAds: true (all plans) blocks common ad requests and hides common ad and consent containers with CSS.
  • hideSelectors (Growth+) hides elements you name. Use it when you know the selectors.
  • aiRemoval (Growth+) detects and hides cookie-banner, newsletter, chat-widget, social-overlay and ad elements.

The cookie banner guide and the AI element removal guide cover these in depth.

What timing controls can't fix

Some limits come from how the capture browser is configured, not from timing. These were checked against the renderer source on 13 November 2026.

  • WebSocket-fed content. WebSocket connections are blocked. A dashboard that only receives data over a socket will stay in its loading state. Give screenshot views an HTTP data path or a server-rendered snapshot route.
  • Video and audio. Media requests are blocked, so <video> elements show their poster image or nothing. Set a poster if the frame matters.
  • Web fonts in viewport captures. Font requests are currently skipped for viewport-only captures and loaded for fullPage: true captures. If text appears in a fallback font, try the same request with fullPage: true.
  • Pages that never go idle. Constant polling makes waitForNetworkIdle time out. Use a selector wait instead.
  • Very long waits. Navigation alone can take up to 30 seconds. Keep delay, scrolling and script time modest, and test the total.

A debug ladder

When a capture looks wrong, change one thing at a time:

  1. Capture with no waits. This is your baseline.
  2. Add waitForSelector for the content you expect. Did the output change?
  3. Add waitForNetworkIdle: true. If the request now times out, the page never goes quiet, so remove it.
  4. Add a short delay (500–1500 ms) for animations and image decoding.
  5. Ask for format: "html" (Basic+). It returns the DOM as it was at capture time, so you can check whether the content existed and whether your selector matched.
  6. Add javascript (Growth+) only once you know what state is missing.

Start in the playground to test visual settings quickly, then move the working request into code. The full parameter list is in the API reference.

Get an API key. The Free plan includes 100 captures, and the pricing page lists which plan unlocks each control.

dynamic content
spa
lazy loading
javascript
technical

About the Author

Asad Ali

Asad Ali

CTO at ZTABS and the developer behind Screenshotly. Writes about screenshot automation, API design, and building reliable SaaS backends with Next.js, Node.js, and TypeScript.

Credentials: CTO at ZTABS, full-stack developer, builder and maintainer of Screenshotly and its official JavaScript and Python clients

Frequently Asked Questions

What is the most reliable wait strategy for a React or Vue app?

Have the app mark itself ready, for example by setting data-screenshot-ready="true" on the root element once data and charts have rendered, and send waitForSelector: '[data-screenshot-ready="true"]'. Add waitForNetworkIdle: true if the page fetches data after hydration. A fixed delay is a fallback, not a strategy.

Does waitForSelector fail the request if the element never appears?

No. Screenshotly waits up to 10 seconds for the selector and then captures anyway. If you need a hard failure, capture an element with the selector parameter instead: when that element is missing the API returns a 400 error.

Does fullPage: true trigger lazy-loaded images?

No. A full-page capture photographs the document at its current height without scrolling it first, so images that load on scroll may still be placeholders. Use the scroll option (Growth plan and above) or a javascript snippet that scrolls the page before capture.

How do I stop CSS animations from blurring a capture?

On the Growth plan and above, send a javascript snippet that injects a style tag setting animation and transition durations to 0s and then calls finish() on running Web Animations. Elements without animation-fill-mode forwards return to their base styles, so check the result once.

Which plan do I need for these controls?

waitForSelector, waitForNetworkIdle, delay, fullPage, darkMode and blockAds work on every plan. javascript, scroll, hideSelectors and aiRemoval need Growth or Scale. HTML output, which is useful for debugging, needs Basic or above.

Ready to capture your first screenshot?

Get started with 100 free screenshots. No credit card required.

Related Articles