Capture options

Options shape every part of a capture: the size of the window, the device the page thinks it runs on, when the shot is taken and what the page is allowed to do. Each one has a sensible default, so you only send the ones you want to change.

Passing optionsLink to this section

Put them in the options object of the request. This one captures the mobile version of a site, in dark mode, from top to bottom:

import { Url2Image } from '@url2image/sdk'

const { success, data, message } = await Url2Image({
    url: 'https://example.com',
    token: process.env.URL2IMAGE_TOKEN,
    options: {
        width: 390,
        height: 844,
        hasTouch: true,
        userAgent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1',
        themeMode: 'dark',
        fullPage: true
    }
})

OutputLink to this section

What comes back, and how much of the page it covers.

• storagebooleandefault true

  Host the image on the CDN and return its link. Set it to false to get the image only as base64, for 0.25 credits.

• fullPagebooleandefault false

  Capture the whole scrollable page instead of just the viewport.

Viewport and deviceLink to this section

The size of the browser window and the device the page thinks it runs on.

• widthnumberdefault 1080

  Viewport width in pixels, up to 10000.

• heightnumberdefault 720

  Viewport height in pixels, up to 10000.

• hasTouchbooleandefault false

  Present the browser as a touch device.

• themeMode"auto" | "light" | "dark" | "no-preference"default "auto"

  The color scheme the page sees, for sites with a dark mode.

TimingLink to this section

When the capture happens, and what moving parts look like.

• takeScreenshotWhen"load" | "domcontentloaded" | "networkidle" | "commit"default "load"

  Which loading step to wait for before capturing.

• waitBeforeScreenshotnumberdefault 0

  Extra time to wait before the capture, in milliseconds, up to 60000.

• allowAnimationsbooleandefault true

  Set it to false to freeze CSS animations and transitions during the capture.

Page behaviorLink to this section

What the browser lets the page do while it loads.

• allowJsbooleandefault true

  Run the page JavaScript.

• allowServiceWorkersbooleandefault true

  Let the page register service workers.

• bypassCSPbooleandefault false

  Ignore the page Content Security Policy, which some custom scripts and styles need.

• offlinebooleandefault false

  Load the page with the network switched off.

Request and identityLink to this section

How the browser presents itself to the site.

• userAgentstringdefault Browser default

  A custom user agent, for example a mobile browser.

• localestringdefault Browser default

  The language and region the page sees, such as en-US or de-DE.

• headersobjectdefault None

  Extra request headers sent with every request of the page, up to 50.

• refererstringdefault None

  The referer sent with the page request.

Custom codeLink to this section

Your own JavaScript and CSS, added right before the capture.

• scriptstringdefault None

  JavaScript added to the page right before the capture.

• stylesstringdefault None

  CSS added to the page right before the capture.

Defaults and validationLink to this section

Options never make a request fail. A value the API cannot use is replaced by the default, so a typo costs you the setting, not the capture.

• Every option is optional. Leave out the ones you do not need.
• Switches take a JSON true or false. Anything else, the strings "true" and "false" included, keeps the default.
• Numbers can be sent as numbers or as digits in a string. Values above the maximum are capped at the maximum.
• Options with a list of values fall back to their default for anything outside the list.
• Empty strings are ignored, and option names the API does not know are skipped.