# capture-website

> Capture screenshots of websites

Latest version **5.1.0** (published 2025-10-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install capture-website
pnpm add capture-website
yarn add capture-website
bun add capture-website
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.1.0 |
| Published | 2025-10-31 |
| First published | 2019-02-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=20 |
| Dependencies | 4 |
| Unpacked size | 60.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2011 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | capture, screenshot, website, page, url, screen, webshot, puppeteer, chrome, chromium, image, png, jpg, jpeg |

## Links

- npm: https://www.npmjs.com/package/capture-website
- Repository: https://github.com/sindresorhus/capture-website
- Homepage: https://github.com/sindresorhus/capture-website#readme
- Issues: https://github.com/sindresorhus/capture-website/issues
- Funding: https://github.com/sponsors/sindresorhus
- npm.io page: https://npm.io/package/capture-website

## Dependencies (4)

- [file-url](https://npm.io/package/file-url.md) ^4.0.0
- [puppeteer](https://npm.io/package/puppeteer.md) ^24.27.0
- [tough-cookie](https://npm.io/package/tough-cookie.md) ^6.0.0
- [@ghostery/adblocker-puppeteer](https://npm.io/package/@ghostery/adblocker-puppeteer.md) ^2.12.5

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@uppy/url](https://npm.io/package/@uppy/url.md) — 185.8K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads

## Recent versions

- 5.1.0 (latest) — 2025-10-31
- 5.0.1 — 2025-09-30
- 5.0.0 — 2025-09-08
- 4.2.0 — 2024-12-03
- 4.1.0 — 2024-01-29
- 4.0.1 — 2024-01-25
- 4.0.0 — 2023-11-06
- 3.2.0 — 2022-10-26
- 3.1.0 — 2022-08-29
- 3.0.1 — 2022-08-22
- 3.0.0 — 2022-08-11
- 2.4.1 — 2022-08-11
- 2.4.0 — 2022-05-13
- 2.3.0 — 2022-02-02
- 2.2.0 — 2022-01-22
- … 33 more at https://npm.io/package/capture-website/versions

## README

# capture-website

> Capture screenshots of websites

It uses [Puppeteer](https://github.com/GoogleChrome/puppeteer) (Chrome) under the hood.

See [capture-website-cli](https://github.com/sindresorhus/capture-website-cli) for the command-line tool.

## Install

```sh
npm install capture-website
```

Note to Linux users: If you get a sandbox-related error, you need to enable [system sandboxing](#i-get-a-sandbox-related-error).

## Usage

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('https://sindresorhus.com', 'screenshot.png');
```

## API

### captureWebsite.file(input, outputFilePath, options?)

Capture a screenshot of the given `input` and save it to the given `outputFilePath`.

Intermediate directories are created for you if they do not exist.

Returns a `Promise<void>` that resolves when the screenshot is written.

### captureWebsite.buffer(input, options?)

Capture a screenshot of the given `input`.

Returns a `Promise<Uint8Array>` with the screenshot as binary.

### captureWebsite.base64(input, options?)

Capture a screenshot of the given `input`.

Returns a `Promise<string>` with the screenshot as [Base64](https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/Base64_encoding_and_decoding).

#### input

Type: `string`

The URL, file URL, data URL, local file path to the website, or HTML.

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('index.html', 'local-file.png');
```

#### options

Type: `object`

##### inputType

Type: `string`\
Default: `'url'`\
Values: `'url' | 'html'`

Set it to `html` to treat `input` as HTML content.

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('<h1>Awesome!</h1>', 'screenshot.png', {
	inputType: 'html'
});
```

##### width

Type: `number`\
Default: `1280`

Page width.

##### height

Type: `number`\
Default: `800`

Page height.

##### type

Type: `string`\
Values: `'png' | 'jpeg' | 'webp' | 'pdf'`\
Default: `'png'`

Output type.

> [!NOTE]
> When using `'pdf'`, the `clip`, `element`, and `quality` options are not supported. Use the `pdf` option for PDF-specific settings.

##### quality

Type: `number`\
Values: `0...1`\
Default: `1`

Image quality. Only for `{type: 'jpeg'}` and `{type: 'webp'}`.

##### scaleFactor

Type: `number`\
Default: `2`

Scale the webpage `n` times.

The default is what you would get if you captured a normal screenshot on a computer with a retina (High DPI) screen.

##### emulateDevice

Type: `string`\
Values: [Devices](https://github.com/puppeteer/puppeteer/blob/main/packages/puppeteer-core/src/common/Device.ts) *(Use the `name` property)*

Make it look like the screenshot was taken on the specified device.

This overrides the `width`, `height`, `scaleFactor`, and `userAgent` options.

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('https://sindresorhus.com', 'screenshot.png', {
	emulateDevice: 'iPhone X'
});
```

##### fullPage

Type: `boolean`\
Default: `false`

Capture the full scrollable page, not just the viewport.

> [!WARNING]
> Screenshots taller than 16384px will repeat content due to a Chromium limitation. Use the `clip` option to capture sections separately.

##### preloadLazyContent

Type: `boolean`\
Default: `false`

Scroll through the entire page to trigger lazy-loaded content before capturing the screenshot.

This scrolls through the page viewport by viewport, waiting for network idle after each scroll, then returns to the original scroll position. This is useful for capturing third-party widgets, marketing banners, or any content that only loads when scrolled into view.

> [!NOTE]
> This option is automatically enabled when `fullPage` is `true`.

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('https://example.com', 'screenshot.png', {
	preloadLazyContent: true
});
```

##### defaultBackground

Type: `boolean`\
Default: `true`

Include the default white background.

Disabling this lets you capture screenshots with transparency.

##### timeout

Type: `number` *(seconds)*\
Default: `60`

The number of seconds before giving up trying to load the page.

Specify `0` to disable the timeout.

##### throwOnHttpError

Type: `boolean`\
Default: `false`

Throw an error if the HTTP response status code is not in the 200-299 range.

This only applies to `http://` and `https://` URLs. Local files, data URLs, and HTML content are not affected.

```js
import captureWebsite from 'capture-website';

// Throws an error if the page returns a 404, 500, etc.
await captureWebsite.file('https://example.com/missing', 'screenshot.png', {
	throwOnHttpError: true
});
```

##### delay

Type: `number` *(seconds)*\
Default: `0`

The number of seconds to wait after the page finished loading before capturing the screenshot.

This can be useful if you know the page has animations that you like it to finish before capturing the screenshot.

This is also useful for capturing lazy-loaded content from third-party scripts (marketing widgets, analytics, etc.) that load asynchronously after the initial page load.

##### waitForElement

Type: `string`

Wait for a DOM element matching the given [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to appear in the page and to be visible before capturing the screenshot. It times out after `options.timeout` seconds.

##### element

Type: `string`

Capture the DOM element matching the given [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors). It will wait for the element to appear in the page and to be visible. It times out after `options.timeout` seconds. Any actions performed as part of `options.beforeScreenshot` occur before this.

##### hideElements

Type: `string[]`

Hide DOM elements matching the given [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors).

Can be useful for cleaning up the page.

This sets [`visibility: hidden`](https://stackoverflow.com/a/133064/64949) on the matched elements.

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('https://sindresorhus.com', 'screenshot.png', {
	hideElements: [
		'#sidebar',
		'img.ad'
	]
});
```

##### removeElements

Type: `string[]`

Remove DOM elements matching the given [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors).

This sets [`display: none`](https://stackoverflow.com/a/133064/64949) on the matched elements, so it could potentially break the website layout.

##### clickElement

Type: `string`

Click the DOM element matching the given [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors).

##### scrollToElement

Type: `string | object`

Scroll to the DOM element matching the given [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors).

###### element

Type: `string`

A [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors).

###### offsetFrom

Type: `string`\
Values: `'top' | 'right' | 'bottom' | 'left'`

Offset origin.

###### offset

Type: `number`

Offset in pixels.

##### disableAnimations

Type: `boolean`\
Default: `false`

Disable CSS [animations](https://developer.mozilla.org/en-US/docs/Web/CSS/animation) and [transitions](https://developer.mozilla.org/en-US/docs/Web/CSS/transition).

##### blockAds

Type: `boolean`\
Default: `true`

[Ad blocking.](https://github.com/ghostery/adblocker/blob/master/packages/adblocker-puppeteer/README.md)

##### isJavaScriptEnabled

Type: `boolean`\
Default: `true`

Whether JavaScript on the website should be executed.

This does not affect the `scripts` and `modules` options.

##### modules

Type: `string[]`

Inject [JavaScript modules](https://developers.google.com/web/fundamentals/primers/modules) into the page.

Accepts an array of inline code, absolute URLs, and local file paths (must have a `.js` extension).

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('https://sindresorhus.com', 'screenshot.png', {
	modules: [
		'https://sindresorhus.com/remote-file.js',
		'local-file.js',
		`
		document.body.style.backgroundColor = 'red';
		`
	]
});
```

##### scripts

Type: `string[]`

Same as the `modules` option, but instead injects the code as [`<script>` instead of `<script type="module">`](https://developers.google.com/web/fundamentals/primers/modules). Prefer the `modules` option whenever possible.

##### styles

Type: `string[]`

Inject CSS styles into the page.

Accepts an array of inline code, absolute URLs, and local file paths (must have a `.css` extension).

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('https://sindresorhus.com', 'screenshot.png', {
	styles: [
		'https://sindresorhus.com/remote-file.css',
		'local-file.css',
		`
		body {
			background-color: red;
		}
		`
	]
});
```

##### headers

Type: `object`\
Default: `{}`

Set custom [HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('https://sindresorhus.com', 'screenshot.png', {
	headers: {
		'x-powered-by': 'https://github.com/sindresorhus/capture-website'
	}
});
```

##### userAgent

Type: `string`

Set a custom [user agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent).

##### referrer

Type: `string`

Set a custom [referrer header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) for the page navigation.

This takes preference over the referrer header value set by the `headers` option.

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('https://example.com', 'screenshot.png', {
	referrer: 'https://google.com'
});
```

##### pdf

Type: `object`

PDF-specific options. Only applies when `type` is `'pdf'`.

The object can have the following properties:

- `format` (string): Paper format. Values: `'letter' | 'legal' | 'tabloid' | 'ledger' | 'a0' | 'a1' | 'a2' | 'a3' | 'a4' | 'a5' | 'a6'`. Default: `'letter'`
- `landscape` (boolean): Use landscape orientation. Default: `false`
- `margin` (object): Set page margins. Accepts string values (e.g., '10px', '2cm') or numeric values in pixels. Object with `top`, `right`, `bottom`, `left` properties.
- `background` (boolean): Include background graphics. Default: `false`

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('https://example.com', 'output.pdf', {
	type: 'pdf',
	pdf: {
		format: 'a4',
		landscape: true,
		margin: {
			top: '20px',
			right: '20px',
			bottom: '20px',
			left: '20px'
		},
		background: true
	}
});
```

##### cookies

Type: `Array<string | object>`

Set cookies in [browser string format](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) or [object format](https://pptr.dev/api/puppeteer.page.setcookie).

Tip: Go to the website you want a cookie for and [copy-paste it from DevTools](https://stackoverflow.com/a/24961735/64949).

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('https://sindresorhus.com', 'screenshot.png', {
	cookies: [
		// This format is useful for when you copy it from the browser
		'id=unicorn; Expires=Wed, 21 Oct 2018 07:28:00 GMT;',

		// This format is useful for when you have to manually create a cookie
		{
			name: 'id',
			value: 'unicorn',
			expires: Math.round(new Date('2018-10-21').getTime() / 1000)
		}
	]
});
```

##### authentication

Type: `object`

Credentials for [HTTP authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication).

###### username

Type: `string`

###### password

Type: `string`

##### beforeNavigation

Type: `Function`

The specified function is called right before navigating to the page. It receives the Puppeteer [`Page` instance](https://pptr.dev/api/puppeteer.page) as the first argument and the [`browser` instance](https://pptr.dev/api/puppeteer.browser) as the second argument. This is useful for registering event handlers that need to be set up before page navigation, such as dialog handlers or request interceptors. The function can be async.

> [!CAUTION]
> Do not register event listeners on the `browser` object. Browser listeners persist and cause memory leaks. Only register listeners on the `page` object.

Note: Do not call `page.close()`, `browser.close()`, or `page.goto()`.

**Example: Handling a dialog during page load**

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('https://example.com', 'screenshot.png', {
	beforeNavigation: async page => {
		page.once('dialog', async dialog => {
			await dialog.dismiss();
		});
	}
});
```

**Example: Blocking requests**

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('https://example.com', 'screenshot.png', {
	beforeNavigation: async page => {
		await page.setRequestInterception(true);

		// Important: Every request must call continue() or abort()
		page.on('request', request => {
			if (['image', 'font'].includes(request.resourceType())) {
				request.abort();
			} else {
				request.continue();
			}
		});
	}
});
```

##### beforeScreenshot

Type: `Function`

The specified function is called right before the screenshot is captured, as well as before any bounding rectangle is calculated as part of `options.element`. It receives the Puppeteer [`Page` instance](https://pptr.dev/api/puppeteer.page) as the first argument and the [`browser` instance](https://pptr.dev/api/puppeteer.browser) as the second argument. This gives you a lot of power to do custom stuff. The function can be async.

Note: Make sure to not call `page.close()` or `browser.close()`.

```js
import captureWebsite from 'capture-website';
import checkSomething from './check-something.js';

await captureWebsite.file('https://sindresorhus.com', 'screenshot.png', {
	beforeScreenshot: async (page, browser) => {
		await checkSomething();
		await page.click('#activate-button');
		await page.waitForSelector('.finished');
	}
});
```

##### debug

Type: `boolean`\
Default: `false`

Show the browser window so you can see what it's doing, redirect page console output to the terminal, and slow down each Puppeteer operation.

Note: This overrides `launchOptions` with `{headless: false, slowMo: 100}`.

##### onConsole

Type: `Function`

A function that is called whenever the page logs to its console. This allows you to receive and handle console output from the page.

The function receives a Puppeteer [`ConsoleMessage`](https://pptr.dev/api/puppeteer.consolemessage) object as its argument, which provides access to the console message text, type, location, and more.

Note: Errors thrown in the callback are caught to prevent breaking the screenshot capture. If `debug` is enabled, errors are logged to the console.

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('https://example.com', 'screenshot.png', {
	onConsole: message => {
		console.log(`[${message.type()}] ${message.text()}`);
	}
});
```

##### darkMode

Type: `boolean`\
Default: `false`

Emulate preference of dark color scheme ([`prefers-color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)).

##### inset

Type: `object | number`\
Default: `0`

Inset the bounding box of the screenshot.

Accepts an object `{top?: number; right?: number; bottom?: number; left?: number}` or a `number` as a shorthand for all directions.

Positive values, for example `inset: 10`, will decrease the size of the screenshot.
Negative values, for example `inset: {left: -10}`, will increase the size of the screenshot.

Note: This option is ignored if the `fullPage` option is set to `true`. Can be combined with the `element` option.
Note: When the `width` or `height` of the screenshot is equal to `0` an error is thrown.

Example: Include 10 pixels around the element.

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('index.html', 'screenshot.png', {
	element: '.logo',
	inset: -10
});
```

Example: Ignore 15 pixels from the top of the viewport.

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('index.html', 'screenshot.png', {
	inset: {
		top: 15
	}
});
```

##### allowCORS

Type: `boolean`\
Default: `false`

Allow cross-origin requests. Useful when capturing local HTML files that reference other local files.

**Warning:** This disables web security features and should only be used in trusted environments.

```js
await captureWebsite.file('file:///path/to/local/file.html', 'screenshot.png', {
	allowCORS: true
});
```

##### waitForNetworkIdle

Type: `boolean`\
Default: `false`

Wait for all network connections to finish before capturing the screenshot.

This can be useful for websites that have long-running requests or many resources to load.

Note: This uses Puppeteer's `networkidle0` instead of the default `networkidle2`.

##### launchOptions

Type: `object`\
Default: `{headless: true}`

Options passed to [`puppeteer.launch()`](https://pptr.dev/api/puppeteer.puppeteernodelaunchoptions).

Note: Some of the launch options are overridden by the `debug` option.

To capture screenshots of websites with self-signed certificates, set `acceptInsecureCerts: true`:

```js
await captureWebsite.file('https://localhost:8080', 'screenshot.png', {
	launchOptions: {
		acceptInsecureCerts: true
	}
});
```

##### overwrite

Type: `boolean`\
Default: `false`

Overwrite the destination file if it exists instead of throwing an error.

*This option applies only to `captureWebsite.file()`.*

##### preloadFunction

Type: `string | Function`\
Default: `undefined`

Inject a function to be executed prior to navigation.

This can be useful for [altering the JavaScript environment](https://pptr.dev/api/puppeteer.page.evaluateonnewdocument). For example, you could define a global method on the `window`, overwrite `navigator.languages` to change the language presented by the browser, or mock `Math.random` to return a fixed value.

##### preloadFunctionArguments

Type: `Array`\
Default: `[]`

Arguments to pass to the `preloadFunction`.

The arguments must be serializable (JSON-serializable values, not functions or DOM elements).

```js
await captureWebsite.file('https://example.com', 'screenshot.png', {
	preloadFunction: (customValue, anotherValue) => {
		window.myValue = customValue;
		window.myOtherValue = anotherValue;
	},
	preloadFunctionArguments: ['Hello', 42]
});
```

##### clip

Type: `object`

Define the screenshot's position and size (clipping region).

The position can be specified through `x` and `y` coordinates which starts from the top-left.

This can be useful when you only need a part of the page.

You can also consider using `element` option when you have a [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors).

Note that `clip` is mutually exclusive with the `element` and `fullPage` options.

- **x** - X-coordinate where the screenshot starts.
Type: `number`
- **y** - Y-coordinate where the screenshot starts.
Type: `number`
- **width** - The width of the screenshot.
Type: `number`
- **height** - The height of the screenshot.
Type: `number`

For example, define the screenshot's `width` and `height` to 400 at position (0, 0):

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('https://sindresorhus.com', 'screenshot.png', {
	clip: {
		x: 0,
		y: 0,
		width: 400,
		height: 400
	}
});
```

### devices

Type: `string[]`

Devices supported by the `emulateDevice` option.

```js
import captureWebsite, {devices} from 'capture-website';

console.log(devices);
//=> ['iPhone 13', 'iPad Pro', …]
```

## Tips

### Capturing multiple screenshots

**Avoid unlimited concurrency** as each capture creates a new browser instance. Use a concurrency limiter like [`p-limit`](https://github.com/sindresorhus/p-limit):

```js
import pLimit from 'p-limit';
import captureWebsite from 'capture-website';

const limit = pLimit(2); // Limit to 2 concurrent captures

const items = [
	['https://sindresorhus.com', 'sindresorhus'],
	['https://github.com', 'github'],
	// …
];

await Promise.all(items.map(([url, filename]) => {
	return limit(() => captureWebsite.file(url, `${filename}.png`));
}));
```

Or use [`p-map`](https://github.com/sindresorhus/p-map):

```js
import pMap from 'p-map';
import captureWebsite from 'capture-website';

const items = [
	['https://sindresorhus.com', 'sindresorhus'],
	['https://github.com', 'github'],
	// …
];

await pMap(items, async ([url, filename]) => {
	await captureWebsite.file(url, `${filename}.png`);
}, {concurrency: 2});
```

*Check out [`filenamify-url`](https://github.com/sindresorhus/filenamify-url) if you need to create a filename from the URL.*

## FAQ

### I'm getting a sandbox-related error

If you get an error like `No usable sandbox!` or `Running as root without --no-sandbox is not supported`, you need to properly [set up sandboxing](https://pptr.dev/troubleshooting#setting-up-chrome-linux-sandbox) on your Linux instance.

Alternatively, if you completely trust the content, you can disable sandboxing (strongly discouraged):

```js
import captureWebsite from 'capture-website';

await captureWebsite.file('…', '…', {
	launchOptions: {
		args: [
			'--no-sandbox',
			'--disable-setuid-sandbox'
		]
	}
});
```

### How is this different from your [Pageres](https://github.com/sindresorhus/pageres) project?

The biggest difference is that Pageres supports capturing multiple screenshots in a single call and it automatically generates the filenames and writes the files. Also, when projects are popular and mature, like Pageres, it becomes harder to make drastic changes. There are many things I would change in Pageres today, but I don't want to risk making lots of breaking changes for such a large userbase before I know whether it will work out or not. So this package is a rethink of how I would have made Pageres had I started it today. I plan to bring some things back to Pageres over time.

## Related

- [capture-website-cli](https://github.com/sindresorhus/capture-website-cli) - CLI for this module
- [pageres](https://github.com/sindresorhus/pageres) - A different take on screenshotting websites

---
_Source: https://npm.io/package/capture-website · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._