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.
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.
- Navigate. The browser loads
urland waits forDOMContentLoaded. WithwaitForNetworkIdle: trueit waits instead until the network has gone quiet (Puppeteer'snetworkidle0). Navigation times out after 30 seconds. - Ad-blocking CSS is injected if
blockAdsis true. waitForSelectorwaits up to 10 seconds for the selector. If it never appears, the request carries on.javascriptruns in the page. If it returns a promise, Screenshotly waits for it, then pauses about 300 ms.delaywaits a fixed number of milliseconds (maximum 10,000).hideSelectorsare hidden with injected CSS.aiRemovalhides detected overlays.scrollscrolls the page bydistancepixels atspeedpixels per second, returns to the top and waits about 500 ms.- Capture. The viewport, the full page, a
cliprectangle or aselectorelement is captured.
Two consequences matter in practice:
delayruns after yourjavascript. That makes it a good settling buffer for work your script started.scrollruns last, afterdelay. Images it triggers get only the built-in half-second before the capture. If they need longer, scroll fromjavascriptinstead, so thedelayruns 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 .barorsvg 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.
Menus, tabs and modals (Growth+)
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 hidescookie-banner,newsletter,chat-widget,social-overlayandadelements.
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 aposterif the frame matters. - Web fonts in viewport captures. Font requests are currently skipped for viewport-only captures and loaded for
fullPage: truecaptures. If text appears in a fallback font, try the same request withfullPage: true. - Pages that never go idle. Constant polling makes
waitForNetworkIdletime 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:
- Capture with no waits. This is your baseline.
- Add
waitForSelectorfor the content you expect. Did the output change? - Add
waitForNetworkIdle: true. If the request now times out, the page never goes quiet, so remove it. - Add a short
delay(500–1500 ms) for animations and image decoding. - 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. - 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.
Related guides
- Visual regression testing with screenshots: stable captures matter most when you diff them.
- Capturing responsive mobile screenshots
- Screenshot API error handling
Get an API key. The Free plan includes 100 captures, and the pricing page lists which plan unlocks each control.
About the Author

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.