@browserless/screenshot

@browserless/screenshot: Take a clean screenshot of any website.

See the screenshot section on our website for more information.

Install

Using npm:

npm install @browserless/screenshot --save

About

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.

What this package does

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

Usage

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%)'
  }
})

Options

All Puppeteer page.screenshot() options are supported.

Browser Overlay

Add a browser frame around your screenshot for a polished look:

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

// Solid color
overlay: { background: '#c1c1c1' }

// CSS gradient
overlay: { background: 'linear-gradient(45deg, #12c2e9, #c471ed, #f64f59)' }

// Image URL
overlay: { background: 'https://picsum.photos/1920/1080' }

Element Screenshots

Capture a specific DOM element:

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'
})

Full Page Screenshots

Capture the entire scrollable page with lazy-loaded content:

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

Code Syntax Highlighting

When the response is JSON or plain text, the package automatically renders it with syntax highlighting:

// 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 automad-prism-themes and prism-themes. When a theme exists in both, the automad version is used.

Some themes also offer light/dark combo variants that bundle both modes in a single CSS file, switching automatically based on the page's dark mode class. Since screenshots render without a dark mode context, the light variant will always be used — prefer explicit themes like github-light or github-dark instead.

Available combo themes:

Smart Content Detection

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.

Examples

Social media card

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

const buffer = await browserless.screenshot('https://api.example.com/docs', {
  fullPage: true,
  type: 'jpeg',
  quality: 85
})

Specific component

const buffer = await browserless.screenshot('https://example.com', {
  element: '[data-testid="pricing-table"]',
  type: 'png'
})

Architecture

@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

How it fits in the monorepo

This is a core functionality package for screenshot capture:

Dependencies

License

@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