Full-Page vs Viewport Screenshots: When to Use Each (With Examples)

The difference between a full-page screenshot and a viewport screenshot sounds simple, but it produces meaningfully different results — and choosing the wrong one is the most common reason screenshot outputs don't match expectations.

Viewport screenshot: Captures exactly what a user would see in a browser window of the specified dimensions. Content below the fold is not captured. If the page has a sticky header and footer, those are included. If there's a modal or overlay visible in the viewport, that's captured too.

Full-page screenshot: Captures the entire scrollable height of the page — everything from the top of the document to the very bottom, regardless of viewport height. A long article might render as a 10,000-pixel-tall image.

Neither is universally better. The right choice depends on what you're trying to capture and how you'll use the image.

When to Use Viewport Screenshots

Dashboard and app screenshots: Dashboards are designed to fit in a viewport. The charts, tables, and widgets are sized to be visible without scrolling. A full-page screenshot of a dashboard often captures a large expanse of empty space at the bottom where the viewport ends and the document continues.

import requests

# Viewport screenshot of a dashboard at 1920x1080
response = requests.get(
    "https://api.hermesforge.dev/api/screenshot",
    params={
        "url": "https://app.example.com/dashboard",
        "width": 1920,
        "height": 1080,
        "full_page": "false"  # Default behavior
    },
    headers={"X-API-Key": "your_api_key"}
)

Above-the-fold captures: For thumbnails, social media previews, or "what the page looks like on load" monitoring, the viewport is exactly what you want. The user's first impression is the viewport.

Pages with infinite scroll: Pages that load content dynamically as the user scrolls don't have a defined document height. A full-page screenshot of an infinite scroll page captures only the initially loaded content, which may be misleading. A viewport screenshot captures what a user actually sees.

Mobile previews: Mobile screenshots should use mobile viewport dimensions. A 375x812 viewport (iPhone 14) shows what mobile users see.

# Mobile viewport screenshot
response = requests.get(
    "https://api.hermesforge.dev/api/screenshot",
    params={
        "url": "https://example.com",
        "width": 375,
        "height": 812,
        "full_page": "false"
    },
    headers={"X-API-Key": "your_api_key"}
)

When to Use Full-Page Screenshots

Long-form content: Articles, blog posts, documentation pages, and landing pages have meaningful content below the fold. A full-page screenshot captures the complete narrative — all sections, all images, all text. This is what you want for archiving, sharing, or comparing content changes.

# Full-page screenshot of a long article
response = requests.get(
    "https://api.hermesforge.dev/api/screenshot",
    params={
        "url": "https://docs.example.com/getting-started",
        "width": 1280,
        "full_page": "true"
    },
    headers={"X-API-Key": "your_api_key"}
)
# May produce an image 8000-15000px tall

Visual regression testing: When testing that a page hasn't changed unexpectedly, you want to capture the entire page so that changes to below-fold content are detected. A viewport screenshot would miss a footer that broke.

Legal and compliance archiving: Screenshots for legal or compliance purposes typically need to capture the entire page content, not just the visible portion. Full-page is the standard.

Portfolio and design showcases: Full-page screenshots of websites show the complete design work, not just the hero section.

The Full-Page Height Problem

Full-page screenshots have one significant limitation: the image dimensions are not predictable. A full-page screenshot of nytimes.com might be 3,000px tall on one day and 5,000px tall the next, depending on how many articles are loaded. This creates issues if you're displaying the screenshot in a fixed-size container.

Solutions:

Set a max height: Use the clip parameter to limit the screenshot height while still using full_page mode to ensure the full width is captured:

# Capture full width but limit height to 5000px
response = requests.get(
    "https://api.hermesforge.dev/api/screenshot",
    params={
        "url": "https://example.com",
        "width": 1280,
        "full_page": "true",
        "clip": "0,0,1280,5000"  # x,y,width,height
    },
    headers={"X-API-Key": "your_api_key"}
)

Use WebP format: Full-page screenshots of content-rich pages can be 5-15MB as PNG. WebP reduces this by 40-60%:

response = requests.get(
    "https://api.hermesforge.dev/api/screenshot",
    params={
        "url": "https://example.com",
        "width": 1280,
        "full_page": "true",
        "format": "webp"
    },
    headers={"X-API-Key": "your_api_key"}
)

Viewport Size Reference

The viewport dimensions you choose determine which breakpoint the page renders at. Using a non-standard viewport can trigger unexpected layout behavior.

When taking full-page screenshots, the height parameter sets the initial viewport height (which affects above-fold rendering) but does not limit the captured height. When full_page=true, the browser scrolls to the full document height before capturing.

Handling Pages That Don't Render Full Height Correctly

Some pages resist full-page capture:

Fixed-height containers: Pages that set height: 100vh on a wrapper element will show the same content regardless of document scroll height. Full-page mode will capture the full document height but the content won't actually be different below the fold. This is a page design issue, not an API issue.

Lazy-loaded images: Images with loading="lazy" don't load until they're near the viewport. A full-page screenshot taken without scrolling may show placeholder spaces where images should be. Use delay to allow JavaScript to finish and consider adding JavaScript injection to disable lazy loading:

disable_lazy = """
document.querySelectorAll('img[loading="lazy"]').forEach(img => {
    img.loading = 'eager';
    if (img.dataset.src) img.src = img.dataset.src;
});
"""

response = requests.get(
    "https://api.hermesforge.dev/api/screenshot",
    params={
        "url": "https://example.com",
        "width": 1280,
        "full_page": "true",
        "js": disable_lazy,
        "delay": 2000
    },
    headers={"X-API-Key": "your_api_key"}
)

Sticky elements repeating: Some sticky elements (headers, navigation bars) re-appear at every scroll position in a full-page capture, resulting in the sticky element appearing multiple times in the final image. Inject JavaScript to remove sticky positioning before capture:

remove_sticky = """
document.querySelectorAll('*').forEach(el => {
    const style = window.getComputedStyle(el);
    if (style.position === 'sticky' || style.position === 'fixed') {
        el.style.position = 'relative';
    }
});
"""

Choosing Between Them: Quick Decision Guide

Use viewport when: - Capturing a dashboard, app, or tool UI - The page is designed to fit in a browser window - You need predictable output dimensions - You're capturing the "first impression" of a page

Use full-page when: - Capturing an article, blog post, or documentation page - Running visual regression tests - Archiving for legal or compliance purposes - Showcasing a full website design

When in doubt: try full_page=false first. If important content is missing, switch to full_page=true.