Capture website screenshots

Capture screenshots of websites in various resolutions. A good way to make sure your websites are responsive.

It's speedy and generates 100 screenshots from 10 different websites in just over a minute.

It can also be used to render SVG images.

$ npm install --global pageres

PhantomJS, which is used for generating the screenshots, is installed automagically, but in some rare cases it might fail to and you'll get an Error: spawn EACCES error. Download PhantomJS manually and reinstall pageres if that happens.

Specify urls and screen resolutions as arguments. Order doesn't matter.

If no resolution is specified it will default to 1366x768 which is the most popular resolution.

$ pageres <url> <resolution>
$ pageres <resolution> <url>
# <url> can also be a local file path. 
$ pageres <file> <resolution>

List multiple urls and resolutions for pageres to capture all combinations.

$ pageres <url> <resolution> ...
$ pageres 1024x768 1366x768 # 2 screenshots 
$ pageres 1024x768 # 2 screenshots 
$ pageres 1024x768 1366x768 # 4 screenshots 

Pipe in a newline separated list of urls and screen resolutions which will get merged with the arguments.

# In this case a list of screen resolutions 
$ pageres <url> < screen-resolutions.txt

Group arguments with square brackets.

$ pageres [ <url> <resolution> ] [ <url> <resolution> ]
$ pageres [ <url> <resolution> ... ]
# Mix grouped and single arguments 
$ pageres [ 1024x768 1600x900 ] 1366x768
# Options defined inside a group will override the outer ones. 
$ pageres [ 1024x768 --no-crop ] 1366x768 --crop

Screenshots are saved in the current directory.

# Basic multi-url, multi-resolution usage 
pageres 1366x768 1600x900
# Override outer option within group 
pageres [ 1366x768 1600x900 --no-crop ] [ 1024x768 480x320 ] --crop
# Provide a custom filename template 
pageres 1024x768 --filename '<%= date %> - <%= url %>'
# Capture a specific element 
pageres 1366x768 --selector '.page-header'
# Hide a specific element 
pageres 1366x768 --hide '.page-header'
# Delay and pipe in a list of urls 
pageres --delay 3 1366x768 < urls.txt
# Capture a local file 
pageres unicorn.html 1366x768
# Pipe in resolutions 
cat screen-resolutions.txt | pageres

Verbose output to see errors if you need to troubleshoot.

Crop to the set height.

$ pageres 1024x768 --crop

Delay screenshot capture.

$ pageres 1024x768 --delay 3

Custom filename.

$ pageres 1024x768 --filename '<%= date %> - <%= url %>'

Capture DOM element.

$ pageres 1366x768 --selector '.page-header'

Hide DOM element, can be set multiple times.

$ pageres 1366x768 --hide '.page-header'

Override a global crop option within a group.

$ pageres [ 1366x768 --no-crop ] 1024x768 --crop

Browser cookie, can be set multiple times.

$ pageres 1024x768 --cookie 'foo=bar'

Username for HTTP auth.

Password for HTTP auth.

Scale webpage n of times.

Image format. Either png (default) or jpg.

Custom user agent.

You can persist your commands into a file and run it whenever with eg. sh .pageres:

# .pageres 
pageres [ 1000x1000 --crop ] [ 500x500 ]
pageres [ 1000x1000 --crop ] [ 500x500 ]

Check out grunt-pageres if you're using grunt.

For gulp and broccoli, just use the below API directly. No need for a wrapper plugin.
(If you create a useless gulp/broccoli wrapper plugin for this, my cat will be very sad.)

$ npm install --save pageres
var Pageres = require('pageres');
var pageres = new Pageres({delay: 2})
    .src('', ['480x320', '1024x768', 'iphone 5s'], {crop: true})
    .src('', ['1280x1024', '1920x1080'])
    .dest(__dirname); (err) {

Type: number (seconds)
Default: 0

Delay capturing the screenshot.

Useful when the site does things after load that you want to capture.

Type: boolean
Default: false

Crop to the set height.

Type: array of string, object

A string with the same format as a browser cookie or an object of what phantomjs.addCookie accepts.

Go to the website you want a cookie for and copy-paste it from Dev Tools.

Type: string

Define a customized filename using Lo-Dash templates.
For example <%= date %> - <%= url %>-<%= size %><%= crop %>.

Available variables:

  • url: The URL in slugified form, eg. becomes!blog
  • size: Specified size, eg. 1024x1000
  • width: Width of the specified size, eg. 1024
  • height: Height of the specified size, eg. 1000
  • crop: Outputs -cropped when the crop option is true
  • date: The current date (Y-M-d), eg. 2015-05-18
  • time: The current time (h-m-s), eg. 21-15-11

Type: string

Capture a specific DOM element.

Type: array

Hide an array of DOM elements.

Type: string

Username for authenticating with HTTP auth.

Type: string

Password for authenticating with HTTP auth.

Type: number
Default: 1

Scale webpage n times.

Type: string
Default: png
Values: png, jpg

Image format.

Type: string

Custom user agent.

Add a page to screenshot.

Type: string

URL or local path to the website you want to screenshot.

Type: array

Use a <width>x<height> notation or a keyword.

A keyword is a version of a device from this list. You can also pass in the w3counter keyword to use the ten most popular resolutions from w3counter.

Type: object

Options set here will take precedence over the ones set in the constructor.

Set the destination directory.

Type: string

Run pageres.

Type: function

If you don't set a dest() you'll get items in this callback, which is an array of streams.

Warnings with eg. page errors.

You can use the most popular resolutions for your site with pageres by following these steps:

  • In Google Analytics go to the site for which you want screen resolutions
  • Select Audience => Technology => Browser & OS
  • Click the Screen Resolution link in the middle of the screen
  • Click the Export button at the top, then Google Spreadsheets, and select yes for importing
  • Select all the resolutions and copy them into a new file and save it
  • In your terminal run: pageres < file-from-above-step.txt
  • Break Shot - Desktop app for capturing screenshots of responsive websites.
Sindre SorhusKevin Mårtensson

MIT © Sindre Sorhus