Page Shots

Page Shots is a command line interface for taking screenshots of one or more pages of a website. This is useful for getting screenshots for portfolios.

Install

We recommend installing the library globally so that you can use page-shots on the command line to run some commands.

Page Shots requires [Node.js][node] to run.

npm i -g @aptuitiv/page-shots

Usage

The minimum command to get a screenshot of a page is to specify the URL of the page to get a screenshot of.

page-shots -u https://www.aptuitiv.com

There are many more options that you can use to configure the screenshot. See the Command line usage and actions page for a full list of options.

There are two ways to use the Page Shots library.

1. Specify one or more URLs on the command line to get screenshots for.
2. Use a JSON file to specify one or more URLs and process it on the command line.

Configuration filenames

Instead of specifying the URLs to get sreenshots for and their configuration through the command line options you can do all of that in a JSON file.

You specify the name of the JSON file to use with the -c or --config command line option.

page-shots -c myfile.json

You can specify multiple JSON files to use by passing in multiple file names.

page-shots -c myfile.json  myfile2.json

If you don't use a glob pattern (i.e. don't include a * in the file name) then you can leave the .json extension off.

page-shots -c myfile

is the same as:

page-shots -c myfile.json

You can also use a glob pattern to specify the JSON files to use.

page-shots -c myfile*.json

You can process all of the JSON files in the current directory by passing in a wildcard.

page-shots -c *.json

You can also process all of the JSON files in the screenshots directory by passing in a path.

page-shots -c screenshots/*.json

If you pass in a glob pattern then all of the JSON files that match the pattern will be processed.

page-shots -c myfile*.json myfile2*.json

You can also pass in a mix of file names and glob patterns.

page-shots -c myfile.json myfile2*.json myfile3.json

Filenames and Directories

By default the screenshot will be saved in the same directory that you call the command in and by default the file name will be based on the URL of the page. Also, by default, the screenshot will be a jpg image.

For example, if the URL is https://www.aptuitiv.com then the file name will be www-branchcms-com.jpg.

You can specify a file name for the screenshot. The file name can be just the name without the extension, or if can include the "jpg" or "png" extension. If the file name does not have an extension or it doesn't match either "jpg" or "png" extension then the correct extension based on the type argument will be used.

If the file name does have an extension and the extension is jpg or png, then that will always override the file type. The file type will be set to match the extension.

The file name can include a directory path. For example: screenshots/shot-{stub}-{width}.jpg. If it does then the full path set by the file name will be appended to the directory setting value if that was specified.

Dynamic file names

Instead of specifying a specific file name, you can specify a format to follow. There are a few placeholders that you can use in the file name to be replaced with information about the screenshot.

Placeholder	Description
{domain}	The domain name of the URL. This is the domain name without any subdomains. For example, "aptuitiv.com"
{day}	The day number of the month.
{fit}	fit if the screenshot will only be for the specified width and height. full if the screenshot will be for the full page.
{full}	fit if the screenshot will only be for the specified width and height. full if the screenshot will be for the full page.
{height}	The height of the screenshot or viewport.
{hostname}	The hostname of the URL. This is the domain name and any subdomains.
{hostnameNoWww}	The hostname of the URL. This is the domain name and any subdomains.
{month}	The month number of the year.
{path} or {stub}	The URL path. This would be the part of the URL after the domain name.
{quality}	The image quality of the jpg image.
{secondLevelDomain} or {sld}	The second level domain name of the URL. This is the domain name without the top level domain. For example, "aptuitiv"
{size}	The name of the size. Set with the key value in a size object. If it's not set then the value will be the width and height separated by an "x". For example, 1300x800.
{subdomain}	The subdomain of the URL. This is the subdomain of the URL. For example, "www"
{topLevelDomain} or {tld}	The top level domain name of the URL. This is the top level domain name. For example, "com"
{url}	The filename friendly version of the URL.
{urlNoWww}	The filename friendly version of the URL without the "www." prefix.
{width}	The width of the screenshot.
{year}	The 4-digit year number.

The default file name format is {urlNoWww}-{width}.

When you set the file name format you can optionally set the extension. As long as the extension is "jpg" or "png" then the image will be saved as a "jpg" or "png" image, respectively.

Directories

You can specify a directory to save the screenshots in. The directory will be relative to where you call the command. If the directory does not exist then it will be created.

Full size and fixed size screenshots

By default all screenshots will capture the entire page, not just within the height and width specified. The height value is only used with full size screenshots if the height of the web page is less than the specified height. In that case the screenshot will be the specified height. If the height of the web page is larger than the specified height then the actual height of the page will be used.

You can use the --fit option to only capture the page within the specified height and width.

You can go even further and capture just a clip of the page by using the -clipH, -clipW, -clipX, and -clipY options. You must specify all four parameters for a clip to be taken.

Full size screenshots

There are two ways that full size screenshots are taken.

If the height of the screenshot will be less than the stitchThreshold configuration value, then the native full page screenshot will be taken.

If the height of the screenshot will be greater than the stitchThreshold configuration value, then the screenshot will be stitched together from multiple screenshots.

Both methods are good methods. The stiched method handles taller pages like those with infinite scrolls.

During both methods the page will first be scrolled from top to bottom to trigger any lazy loaded content to load. The scroll size is based on the viewport height, which can be configured with the height, size or sizes options. By default, after each scroll, the page will wait for 400 milliseconds to allow the content to load. This can be configured with the --scrollDelay option.

If the stiched method is used, then the hideStitchSelector option can be used to hide an element during the screenshot process. This is useful for hiding a sticky header or floating element that is present on the page.

You can specify multiple elements to hide by passing in multiple CSS selectors. For example:

page-shots --hideStitchSelector '.js-header' '.js-footer'

In the JSON config file, you can specify the hideStitchSelector value as an array of CSS selectors. For example:

{
    "hideStitchSelector": [".js-header", ".js-footer"]
}

Hiding elements

You can hide elements on the page before taking the screenshot. This is useful for hiding a sticky header or floating element that is present on the page.

The hideSelector option is used to hide elements before any screenshot or scrolling is done. It is used when taking a full page screenshot, a fixed size screenshot, or a clipped screenshot.

The hideStitchSelector option is only used when doing a full page screenshots and the screenshot is created by stitching together multiple screenshots. It can be used to hide elements on the page after the first scroll. This is useful for hiding a sticky header or floating element that is present on the page.

tip

You should only use the hideStitchSelector option to hide floating elements, like a sticky header. Otherwise the resulting screenshot may look off at the bottom as elements are dynamically removed from the page after the original height was set.

Use hideSelector to hide elements that are not floating.

Examples

(The usage for hideSelector is the same as the usage for hideStitchSelector.)

page-shots --hideSelector '.js-header'
page-shots --hideSelector '.js-header' '.js-footer'
page-shots --hideSelector '.js-header' --hideSelector '.js-footer'

{
    "hideSelector": ".js-header"
}

{
    "hideSelector": [".js-header"]
}

{
    "hideSelector": [".js-header", ".js-footer"]
}

Hiding chat widgets

If you need to hide chat widgets that are present on the page then you can use the hideSelector option to hide the chat widget. See the Hiding elements section for more information.

Inspect the page source in your browser and look for the chat widget. Get the CSS selector for the chat widget and use it to hide the chat widget.

page-shots --hideSelector '.js-chat-widget'

{
    "hideSelector": [".js-chat-widget"]
}

Setting screenshot size

There are two ways that you can set the size of the screenshot size. (Note, the screenshot size is always in pixels.)

1. Set the size by setting the width and height values. The height value is only necessary if you want to capture only the exact height and width.
2. Set one or more sizes by setting the size value. The size value requires that both the width and height be set. This does not, however, force the screenshot to only match the exact width and height. By default all screenshots are full size.

Set multiple screenshot sizes on the command line.

Set the screenshot size using the size argument on the command line.

Setting URLs

You can specify the full URL for each web page to capture. Or, if you're getting multiple screenshots in the same website, then you can set the base URL and then just specify the URL path for each web page.

For example, let's say that your website is https://www.mysite.com and you're wanting to capture the home page, the "about us" page and the contact page. You can first set the base URL to be https://www.mysite.com and then simply specify / for the home page, about-us for the about us page, and contact for the contact page.

Note, Page Shots is smart enough to ensure that there is only one / between the base URL and the page path.

Delaying the screenshot

If you need to wait for certain assets to load on the page before taking the screenshot then you set a specific number of milliseconds to wait after the page loads and before the screenshot is taken.

An example scenario could be if you have a Google Map section on the page and you want to make sure that it fully loads before taking the screenshot.

The delay happens after the page has loaded, the page has been scrolled from top to bottom, and right before the screenshot is taken.

Lazy loaded content

Page Shots does it's best to handle lazy loaded content by first scrolling the entire page before taking the screenshot. A small delay of 100ms is then taken before doing the screenshot. The script then waits for all images to return that they have loaded. However, loading doesn't always mean displayed. If the screenshot doesn't display all images then the correct approach would be to add a delay before the screenshot is taking. 500 to 1000 milliseconds is often sufficient.

License

Page Shots is licensed under the MIT license.