Build a practical screenshot-based visual regression workflow for pull requests, previews, and production releases.
A practical introduction to Playwright for testing real user flows, browser behavior, authentication, debugging, CI, and screenshot workflows.
If your screenshot API keeps returning a 'Checking your browser' page instead of the site, the target is behind bot protection. Here's how to capture it with stealth mode.
Developers, marketers, and founders use Allscreenshots to automate website captures. No credit card required to get started.
Website thumbnails turn plain URLs into something people can scan. They help dashboards feel concrete, make directories easier to browse, and give internal tools a quick visual cue before someone clicks.
The hard part is not taking one screenshot. It is generating thumbnails reliably across thousands of URLs: different page sizes, cookie banners, slow pages, broken sites, redirects, dark mode, and pages with no useful Open Graph image.
This guide walks through a practical thumbnail pipeline using a screenshot API.
Website thumbnails show up anywhere a URL needs context:
| Use case | Thumbnail value |
|---|---|
| Link previews | Gives users confidence before opening a URL |
| CRM records | Shows what a prospect's site looks like |
| Directories and marketplaces | Makes listings easier to browse |
| Internal admin tools | Helps support and operations teams identify pages quickly |
| SEO tools | Adds visual context to crawl results |
| Monitoring dashboards | Makes changed pages easier to recognize |
| Bookmark managers | Replaces generic favicons with page previews |
For most of these, the thumbnail does not need to be a full-resolution archive. It needs to be fast, consistent, and good enough to recognize the page.
A thumbnail should come from a predictable frame. Do not let every site decide the image dimensions.
For desktop-style thumbnails, start with 1280 x 720:
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": false,
"viewport": {
"width": 1280,
"height": 720
},
"format": "webp",
"responseType": "url",
"blockAds": true,
"blockCookieBanners": true
}'This captures the first viewport, not the full scrollable page. That is usually the right choice for thumbnails because:
Use full-page screenshots for archives and audits. Use viewport screenshots for thumbnails.
For thumbnails, WebP or JPEG usually makes more sense than PNG.
| Format | Use it when | Tradeoff |
|---|---|---|
| WebP | Your app targets modern browsers | Small files with good quality |
| JPEG | You need broad compatibility | Slight artifacts around text |
| PNG | You need lossless UI detail | Larger files |
| You are creating documents | Not a thumbnail format |
If your thumbnails appear in a dashboard grid, WebP keeps storage and bandwidth down:
{
"url": "https://example.com",
"format": "webp",
"viewport": {
"width": 1280,
"height": 720
},
"responseType": "url"
}If you need compatibility with older systems, use JPEG:
{
"url": "https://example.com",
"format": "jpeg",
"viewport": {
"width": 1280,
"height": 720
},
"responseType": "url"
}Here is a minimal helper:
export async function createWebsiteThumbnail(url) {
const response = await fetch('https://api.allscreenshots.com/v1/screenshots', {
method: 'POST',
headers: {
'X-API-Key': process.env.SCREENSHOT_API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify({
url,
fullPage: false,
viewport: { width: 1280, height: 720 },
format: 'webp',
responseType: 'url',
blockAds: true,
blockCookieBanners: true
})
});
if (!response.ok) {
throw new Error(`Thumbnail failed for ${url}: ${response.status}`);
}
return response.json();
}Use the returned storage URL as the source for your card image:
function WebsiteCard({ site }) {
return (
<article>
<img src={site.thumbnailUrl} alt="" width="320" height="180" />
<h3>{site.name}</h3>
<a href={site.url}>{site.url}</a>
</article>
);
}Keep the image dimensions fixed in the UI. A thumbnail grid should not reflow while images load.
If a user pastes one URL, a synchronous request is fine. If you are importing 500 URLs from a CSV, use async jobs and process results as they finish.
async function queueThumbnail(url) {
const response = await fetch('https://api.allscreenshots.com/v1/screenshots/async', {
method: 'POST',
headers: {
'X-API-Key': process.env.SCREENSHOT_API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify({
url,
fullPage: false,
viewport: { width: 1280, height: 720 },
format: 'webp',
responseType: 'url',
blockAds: true,
blockCookieBanners: true,
webhookUrl: 'https://your-app.example.com/webhooks/thumbnails'
})
});
return response.json();
}Async capture keeps your import job responsive. Your app can show "thumbnail pending" immediately, then update the record when the webhook arrives.
Store the requested capture settings with the thumbnail record. Six months later, you will want to know which viewport, format, and blocking options produced the image.
Most thumbnail systems do not need a fresh screenshot every page view. Cache the result and regenerate only when the page or capture settings change.
A good cache key includes more than the URL:
function thumbnailCacheKey(input) {
return JSON.stringify({
url: input.url,
viewport: input.viewport,
format: input.format,
darkMode: input.darkMode,
blockAds: input.blockAds,
blockCookieBanners: input.blockCookieBanners,
version: 1
});
}Include a version number so you can invalidate every thumbnail after changing your visual style or capture policy.
Refresh rules depend on the product:
| Product | Refresh strategy |
|---|---|
| Bookmark manager | On save, then manually refresh |
| CRM enrichment | On import, then every few months |
| Directory | On listing update or scheduled weekly |
| Monitoring tool | On every scheduled check |
| Link preview | On first paste, then cache aggressively |
Do not regenerate thumbnails on every request unless freshness is core to the product.
Real URL lists are messy. Some pages time out. Some redirect. Some block automation. Some return a blank shell while JavaScript fetches the real content.
Plan for these states:
pending: capture has been queuedready: thumbnail existsfailed: capture failed and can be retriedstale: thumbnail exists but should be refreshedunsupported: URL should not be retried automaticallyIn the UI, a failed thumbnail should not break the whole card. Show a fallback with the site's title, domain, favicon, or initials.
function Thumbnail({ site }) {
if (site.thumbnailStatus !== 'ready') {
return <div className="thumbnailFallback">{new URL(site.url).hostname}</div>;
}
return <img src={site.thumbnailUrl} alt="" width="320" height="180" />;
}This keeps the product usable while background capture catches up.
The capture is only half the job. The UI also needs rules.
Use a fixed aspect ratio:
.thumbnail {
aspect-ratio: 16 / 9;
width: 100%;
object-fit: cover;
background: #f4f4f5;
}Then decide how to handle pages that do not fit:
| Problem | UI decision |
|---|---|
| Very tall page | Capture viewport only |
| Mobile-only site | Use a mobile viewport for that source |
| Dark page in light UI | Add a neutral border |
| Mostly white page | Use a subtle background |
| Failed capture | Show a domain fallback |
Avoid cropping full-page screenshots into tiny cards. They usually become unreadable. A first-viewport thumbnail is a better source image.
If your product previews developer tools, docs, dashboards, or design-heavy sites, dark mode thumbnails may be useful.
{
"url": "https://example.com",
"darkMode": true,
"fullPage": false,
"viewport": {
"width": 1280,
"height": 720
},
"format": "webp",
"responseType": "url"
}Most products should choose one theme for thumbnails and stick to it. Showing a mix of light and dark captures in the same grid can feel inconsistent unless theme is part of the user-facing feature.
A thumbnail is stronger when paired with structured page metadata:
If the site has a good Open Graph image, you may choose that for social cards and use a screenshot only as a fallback. For internal tools and monitoring dashboards, the rendered screenshot is often more useful because it shows the live page, not a marketing image.
For richer extraction workflows, read turn any URL into a screenshot, markdown, and structured data.
A production thumbnail flow usually looks like this:
That architecture keeps the user-facing app fast while the browser work happens in the background.