Capture high-quality screenshots of websites with overlay support, device emulation, and automated image optimization.
npm install @browserless/screenshot> @browserless/screenshot: Take a clean screenshot of any website.
See the screenshot section on our website for more information.
Using npm:
``sh`
npm install @browserless/screenshot --save
This package provides advanced screenshot capture with smart defaults, browser frame overlays, gradient backgrounds, and automatic code syntax highlighting. It wraps Puppeteer's page.screenshot() with features optimized for production use.
The @browserless/screenshot package allows you to:
- Capture screenshots with device emulation and smart waiting
- Add browser frame overlays (dark or light theme)
- Apply gradient or image backgrounds for social media-ready images
- Auto-detect blank screenshots and retry until content renders
- Syntax highlight code (JSON, text) with Prism.js themes
- Capture specific elements using CSS selectors
- Take full-page screenshots with lazy-loaded content support
`js
const createScreenshot = require('@browserless/screenshot')
const createGoto = require('@browserless/goto')
const goto = createGoto({ timeout: 30000 })
const screenshot = createScreenshot({ goto })
// With browserless
const browserless = await browser.createContext()
const buffer = await browserless.screenshot('https://example.com')
// With overlay
const buffer = await browserless.screenshot('https://example.com', {
overlay: {
browser: 'dark',
background: 'linear-gradient(45deg, #FF057C 0%, #8D0B93 50%, #321575 100%)'
}
})
`
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| type | string | 'png' | Image format: 'png', 'jpeg', 'webp' |quality
| | number | — | Quality (0-100) for JPEG/WebP |fullPage
| | boolean | false | Capture full scrollable page |element
| | string | — | CSS selector for element screenshot |codeScheme
| | string | 'atom-dark' | Prism.js theme for code highlighting |waitUntil
| | string | 'auto' | When to consider navigation done |overlay
| | object | {} | Browser overlay options |
All Puppeteer page.screenshot() options are supported.
Add a browser frame around your screenshot for a polished look:
`js`
const buffer = await browserless.screenshot(url, {
overlay: {
// Browser frame theme: 'dark' or 'light'
browser: 'dark',
// Background: color, gradient, or image URL
background: 'linear-gradient(225deg, #FF057C 0%, #8D0B93 50%, #321575 100%)',
// Margin around the screenshot (default: 0.2 = 20%)
margin: 0.2
}
})
#### Background Options
`js
// Solid color
overlay: { background: '#c1c1c1' }
// CSS gradient
overlay: { background: 'linear-gradient(45deg, #12c2e9, #c471ed, #f64f59)' }
// Image URL
overlay: { background: 'https://source.unsplash.com/random/1920x1080' }
`
Capture a specific DOM element:
`js
const buffer = await browserless.screenshot(url, {
element: '.hero-section'
})
// The package waits for the element to be visible
const buffer = await browserless.screenshot(url, {
element: '#main-content'
})
`
Capture the entire scrollable page with lazy-loaded content:
`js`
const buffer = await browserless.screenshot(url, {
fullPage: true
})
The package automatically:
1. Waits for DOM stability
2. Scrolls through the page to trigger lazy-loaded images
3. Scrolls back to top
4. Takes the screenshot
When the response is JSON or plain text, the package automatically renders it with syntax highlighting:
`js`
// Screenshot of a JSON API response
const buffer = await browserless.screenshot('https://api.example.com/data', {
codeScheme: 'atom-dark' // or any Prism.js theme
})
Available themes from prism-themes:
- atom-dark, ghcolors, dracula, duotone-dark, duotone-light, material-dark, material-light, nord, synthwave84, and more
When waitUntil: 'auto' (the default), the package:
1. Navigates to the page
2. Waits for fonts to load
3. Waits for images in viewport to decode
4. Takes a screenshot
5. If the screenshot is blank/white, retries with additional waiting
This ensures JavaScript-rendered content is fully loaded.
#### Social media card
`js`
const buffer = await browserless.screenshot('https://example.com', {
device: 'iPhone 13',
overlay: {
browser: 'light',
background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)'
}
})
#### API documentation screenshot
`js`
const buffer = await browserless.screenshot('https://api.example.com/docs', {
fullPage: true,
type: 'jpeg',
quality: 85
})
#### Specific component
`js`
const buffer = await browserless.screenshot('https://example.com', {
element: '[data-testid="pricing-table"]',
type: 'png'
})
``
@browserless/screenshot
├── src/
│ ├── index.js → Main screenshot logic with smart waiting
│ ├── is-white-screenshot.js → Blank screenshot detection using Jimp
│ ├── time-span.js → Timing utility
│ ├── overlay/
│ │ ├── index.js → Browser frame and background composition
│ │ ├── dark.png → Dark browser frame
│ │ └── light.png → Light browser frame
│ └── pretty/
│ ├── index.js → Code content detection and rendering
│ ├── html.js → HTML template for code display
│ ├── prism.js → Prism.js syntax highlighter
│ └── theme.js → Prism theme loader
└── test/
└── index.js → Tests
This is a core functionality package for screenshot capture:
| Consumer | Purpose |
|----------|---------|
| browserless (core) | Provides the .screenshot() method |@browserless/cli
| | Powers the browserless screenshot command |@browserless/pdf
| | Uses isWhiteScreenshot for content detection |
| Package | Purpose |
|---------|---------|
| @browserless/goto | Page navigation with ad blocking |sharp
| | Image composition for overlays |jimp
| | White/blank screenshot detection |prism-themes
| | Syntax highlighting themes |svg-gradient
| | Generate gradient backgrounds |got
| | Fetch remote background images |is-html-content` | Detect if content is HTML vs code |
|
@browserless/screenshot © Microlink, released under the MIT License.
Authored and maintained by Microlink with help from contributors.
The logo has been designed by xinh studio.
> microlink.io · GitHub microlinkhq · X @microlinkhq