Docs
Render Options

Render Options

Detailing all available render options for Urlbox's rendering API

Basic Options
Basic options for rendering such as setting the URL or HTML, and viewport width and height
Blocking Options
Options for blocking or dismissing certain page elements, such as cookie banners.
Customize Options
Customize the look of the page before rendering a screenshot
Screenshot Options
Options relating to the generated screenshot image
PDF Options
Options relating to PDF document generation.
Cache Options
Options to control how Urlbox caches your screenshots or PDF's. Please note that caching only applies to requests from render links. POST requests to the API are not cached.
Request Options
Options to configure the browser, before navigating to the URL
Wait Options
Options to control how Urlbox waits for the page or elements to load before rendering.
Fail Options
Options to dictate how Urlbox handles certain scenarios.
Page Options
Options to modify the page state before taking a screenshot or PDF
Full Page Options
Advanced options to control how Urlbox takes full page screenshots, when `full_page=true`
Highlighting Options
Options for highlighting a given string on the page. These are useful for either highlighting or hiding (if you use the same foreground and background) words or a given set of characters.
Geolocation Options
Options for the geolocation API.
Storage Options
Options related to storing the screenshots in Amazon S3.

Basic Options

Basic options for rendering such as setting the URL or HTML, and viewport width and height

url

The URL or domain of the website you want to screenshot. We will automatically prepend http:// if it is missing.

url Examples

Screenshot of urlbox.com
Not in view..
Full page screenshot of apple.com
Not in view..
Using a url which contains a query string
Not in view..

html

The HTML you want to render.

html Examples

Preview an HTML email template
Not in view..
Create an Invoice PDF from HTML
Not in view..
Screenshot Gallery in HTML
Not in view..

format

The output format of the resulting render.

The available values are:

png jpeg webp avif svg pdf html mp4 webm md

format Examples

PNG Image
Not in view..
JPEG Image
Not in view..
PDF
Not in view..
SVG
Not in view..
Markdown
Not in view..
HTML
Not in view..
MP4
Not in view..

width

default: 1280

The viewport width of the browser, in pixels.

width Examples

Emulate mobile viewport
Not in view..
Emulate tablet viewport
Not in view..
Emulate desktop viewport
Not in view..
Emulate wide monitor viewport
Not in view..

height

default: 1024

The viewport height of the browser, in pixels.

height Examples

Emulate Iphone 14 Pro Max Viewport Height
Not in view..
Emulate Ipad Pro 12.9 Inch Pro Viewport Height
Not in view..
Emulate Macbook Pro 16 Inch Viewport Height
Not in view..
Emulate Common Desktop Screen Viewport Height
Not in view..

full_page

default: false

Specify whether to capture the full scrollable area of the website. For PDFs, full_page mode will attempt to capture the whole website onto one single page PDF document.

full_page Examples

Full page screenshot of urlbox.com
Not in view..
Full page PDF of urlbox.com
Not in view..

selector

Take a screenshot of the element that matches this selector. By default, if the selector is not found, Urlbox will take a normal viewport screenshot. If you prefer Urlbox to fail the request when the selector is not found, pass fail_if_selector_missing=true.

selector Examples

Select only the Github logo
Not in view..
Snapshotting terms and conditions
Not in view..

clip

Clip the screenshot to the bounding box specified by x,y,width,height.

clip Examples

clip=0,0,400,400
Not in view..
clip=100,100,200,200
Not in view..
clip=0,800,800,600
Not in view..

gpu

default: false

Enable GPU acceleration to render 3D scenes and heavy WebGL content. This is a beta feature and requires pre-approval. Please contact [email protected] to enable this feature on your account.

gpu Examples

WebGL water
Not in view..
WebGL Earth
Not in view..
LLM 3D Visualisation
Not in view..

response_type

For render link requests, setting this option to json will change the response type of the Urlbox request to JSON. For the API, the default response type is JSON.

The available values are:

json binary

response_type Examples

response_type=json
Not in view..
response_type=binary
Not in view..

Blocking Options

Options for blocking or dismissing certain page elements, such as cookie banners.

block_ads

Blocks requests from popular advertising networks from loading.

block_ads Examples

With ads blocked
Not in view..
Without ads blocked
Not in view..

Automatically hides cookie banners from most websites, by setting their style to display: none !important;

hide_cookie_banners Examples

With cookie banners hidden
Not in view..
Without cookie banners hidden
Not in view..

click_accept

Similar to the hide_cookie_banners option, but instead of hiding the banners, this option attempts to click on the 'Accept' button, in order to accept cookies.

click_accept Examples

With click_accept
Not in view..
Without click_accept
Not in view..

block_urls

Block requests from specific domains from loading. You can use wildcard characters such as * to match subdomains.

block_urls Examples

Blocking chat plugin from Urlbox
Not in view..
Without blocking chat plugin from Urlbox
Not in view..

block_images

Blocks image requests

block_images Example

Blocking all images from Unsplash
Not in view..

block_fonts

Blocks font requests

block_fonts Examples

Blocking all font downloads from Urlbox
Not in view..
Without blocking font downloads from Urlbox
Not in view..

block_medias

Block video and audio requests

block_medias Examples

Blocking video and audio requests from Vimeo
Not in view..
Without blocking video and audio requests from Vimeo
Not in view..

block_styles

Prevent stylesheet requests from loading

block_styles Examples

Blocking stylesheets
Not in view..
Without blocking stylesheets
Not in view..

block_scripts

Prevent requests for javascript scripts from loading

block_scripts Examples

Blocking scripts
Not in view..
Without blocking scripts
Not in view..

block_frames

Block frames.

block_frames Example

Blocking frames
Not in view..

block_fetch

Block fetch requests from the target URL.

block_xhr

Block XHR requests from the target URL.

block_xhr Example

Blocking XHR
Not in view..

block_sockets

Block websocket requests.

hide_selector

Comma-delimited string of CSS element selectors that are hidden by setting their style to display: none !important;. Useful for hiding pop-ups.

hide_selector Examples

Hiding an h1 element
Not in view..
Without hiding the h1 element
Not in view..

Customize Options

Customize the look of the page before rendering a screenshot

js

Execute custom JavaScript in the context of the page. The JS gets executed after the page's dom has loaded, but before the screenshot is taken. No need to use load etc event handlers to run code, as these events will already have fired by the time this JS gets executed. You can use await to wait for promises to resolve.

js Examples

Inject a timestamp of the screenshot into the screenshot
Not in view..
Overriding a headline
Not in view..

css

Inject custom CSS into the page

css Examples

Highlight elements with a red border
Not in view..
Changing background colour
Not in view..

dark_mode

default: false

Emulate dark mode on websites by setting prefers-color-scheme: dark

dark_mode Examples

dark_mode=true
Not in view..
dark_mode=false
Not in view..

reduced_motion

Prefer less animations on websites by setting prefers-reduced-motion: reduced

reduced_motion Examples

With reduced motion
Not in view..
Without reduced motion
Not in view..

Screenshot Options

Options relating to the generated screenshot image

retina

default: false

Take a 'retina' or high-definition screenshot, equivalent to setting a device pixel ratio of 2.0 or @2x. Please note that retina screenshots will be double the normal dimensions and will normally take slightly longer to process due to the much bigger image size.

retina Examples

retina=true
Not in view..
retina=false
Not in view..

thumb_width

The width of the generated thumbnail, in pixels. Omit for a full-size screenshot.

thumb_width Examples

thumb_width=100
Not in view..
thumb_width=200
Not in view..
thumb_width=400
Not in view..

thumb_height

The height of the generated thumbnail, in pixels. Omit for a full-size screenshot.

thumb_height Examples

thumb_height=100
Not in view..
thumb_height=200
Not in view..
thumb_height=400
Not in view..

img_fit

default: cover

How the screenshot should be resized or cropped to fit the dimensions when using thumb_width and/or thumb_height options

The available values are:

  • cover - Preserving aspect ratio, attempt to ensure the image covers both thumb_width and/or thumb_height by cropping/clipping to fit.

  • contain - Preserving aspect ratio, contain within both thumb_width and/or thumb_height using letterboxing where necessary.

  • fill - Ignore the aspect ratio and stretch to both thumb_width and/or thumb_height.

  • inside - Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to thumb_width and/or thumb_height.

  • outside - Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to thumb_width and/or thumb_height.

img_fit Examples

img_fit=cover
Not in view..
img_fit=contain
Not in view..
img_fit=fill
Not in view..
img_fit=inside
Not in view..
img_fit=outside
Not in view..

img_position

default: center

How the image should be positioned when using an img_fit of cover or contain.

The available values are:

north northeast east southeast south southwest west northwest center centre

img_position Examples

img_position=north
Not in view..
img_position=south
Not in view..
img_position=west
Not in view..
img_position=east
Not in view..
img_position=center
Not in view..
img_position=northwest
Not in view..
img_fit=contain, img_position=north
Not in view..
img_fit=contain, img_position=south
Not in view..
img_fit=contain, img_position=west
Not in view..
img_fit=contain, img_position=east
Not in view..
img_fit=contain, img_position=center
Not in view..
img_fit=contain, img_position=northwest
Not in view..

img_bg

Background colour to use when img_fit is contain, or img_pad is used, defaults to black without transparency

img_bg Examples

img_bg=red
Not in view..
img_bg=#ccc
Not in view..
img_bg=rgb(180, 255, 200)
Not in view..
img_bg=rgba(180, 255, 200, 0.4)
Not in view..
img_bg=hsl(60, 20%, 20%)
Not in view..

img_pad

Pad the screenshot, giving it a border. Can either be a single pixel value that gets added to each side, or a comma delimited string of top,right,bottom,left pixel values.

img_pad Examples

img_pad=10
Not in view..
img_pad=30
Not in view..
img_pad=1,10,20,40
Not in view..

quality

default: 80

The image quality of the resulting screenshot (JPEG/WebP only)

quality Examples

quality=40
Not in view..
quality=80
Not in view..
quality=100
Not in view..

transparent

default: false

If a website has no background color set, the image will have a transparent background (PNG/WebP only)

max_height

For extremely lengthy websites, it may be preferable to limit the screenshot to a maximum height to prevent Urlbox from spending time scrolling and generating an enormous screenshot.

max_height Example

Short Website
Not in view..

download

Pass in a filename which sets the content-disposition header on the response. E.g. download=myfilename.png This will make the Urlbox link downloadable, and will prompt the user to save the file as myfilename.png

download Example

With a filename
Not in view..

PDF Options

Options relating to PDF document generation.

pdf_page_size

default: A4

Sets the PDF page size.

Setting this option will take precedence over pdf_page_width and pdf_page_height.

The available values are:

A0 A1 A2 A3 A4 A5 A6 Legal Letter Ledger Tabloid

pdf_page_size Examples

pdf_page_size=A0
Not in view..
pdf_page_size=A4
Not in view..
pdf_page_size=Letter
Not in view..

pdf_page_range

Sets the PDF page range to return.

By default, the page is split into a multi page document and returns all page. Use this option to restrict which pages should be returned.

pdf_page_range Examples

Just the first page
Not in view..
The first 2 pages and the 4th page
Not in view..
Just the 4th page
Not in view..

pdf_page_width

Sets the PDF page width, in pixels.

pdf_page_width Examples

pdf_page_width=400
Not in view..
pdf_page_width=800
Not in view..
pdf_page_width=1400
Not in view..

pdf_page_height

Sets the PDF page height, in pixels.

pdf_page_height Examples

pdf_page_height=400
Not in view..
pdf_page_height=800
Not in view..
pdf_page_height=2000
Not in view..

pdf_margin

default: None

Sets the margin of the PDF document.

The available values are:

none default minimum

pdf_margin Examples

pdf_margin=none
Not in view..
pdf_margin=default
Not in view..
pdf_margin=minimum
Not in view..

pdf_margin_top

Sets a custom top margin on the PDF.

pdf_margin_top Example

pdf_margin_top=40
Not in view..

pdf_margin_right

Sets a custom right margin on the PDF.

pdf_margin_right Example

pdf_margin_right=100
Not in view..

pdf_margin_bottom

Sets a custom bottom margin on the PDF.

pdf_margin_bottom Example

pdf_margin_bottom=50
Not in view..

pdf_margin_left

Set a custom left margin on the PDF.

pdf_margin_left Example

pdf_margin_left=60
Not in view..

pdf_auto_crop

Automatically remove white space from PDF. Occasionally a PDF will have a lot of trailing white space at the bottom of the page. This option will attempt to automatically crop the PDF to remove this white space.

pdf_scale

default: 1

Sets the scale factor of the website content in the PDF. Valid values are numbers between 0.1 and 2.

pdf_scale Examples

pdf_scale=0.2
Not in view..
pdf_scale=1.2
Not in view..
pdf_scale=2
Not in view..

pdf_orientation

default: portrait

Sets the orientation of the PDF.

The available values are:

portrait landscape

pdf_orientation Examples

pdf_orientation=portrait
Not in view..
pdf_orientation=landscape
Not in view..

pdf_background

default: true

Sets whether to print background images in the PDF

pdf_background Examples

pdf_background=true
Not in view..
pdf_background=false
Not in view..

disable_ligatures

Prevents ligatures from being used. Useful when rendering a PDF, and you want to extract text which contains ligatures.

disable_ligatures Examples

disable_ligatures=true
Not in view..
disable_ligatures=false
Not in view..

media

default: print

By default, when generating a PDF, the print CSS media query is used. To generate a PDF using the screen CSS, set this option to screen.

media Examples

media=screen
Not in view..
media=print
Not in view..

pdf_show_header

Whether to show the default pdf header on each page of the pdf. The template of the header can be changed by setting the pdf_header option.

pdf_show_header Example

pdf_show_header=true
Not in view..

pdf_header

Change the default pdf header that is shown on each page of the pdf when pdf_show_header option is set.

You have the option to show the following variables in the header (or footer) of the pdf:

  • current date
  • title of the page
  • url of the page
  • current pageNumber
  • the totalPages in the pdf document

You can display these variables by creating empty divs or spans, with special css class names relating to the variable you want to show.

For example, if you want to show the date followed by the url, you could use the following pdf header template:

<div class="date"></div><div class="url"></div>.

The pdf header template you set are inserted as the innerHTML of a parent div which is a flex container, and has align-items set to flex-start.

There are also some helper classes for aligning the divs or spans. The following classes are available:

  • left - adds some left padding to the element and sets flex: none.
  • center - aligns the element and text to the center.
  • right - adds some right padding to the element and sets flex: none.
  • text - sets the text to 8pt.
  • grow - sets flex: auto on the element, allowing it to grow to fill the available space.

The default pdf header is:

<div class='date text left'></div><div class='title text center'></div>.

You can see exactly how the pdf page is constructed by looking at the chromium pdf template in the chromium source repository.

pdf_header Examples

Showing the date and url in the pdf header
Not in view..
Showing the current page and total pages in the pdf header
Not in view..

Whether to show the default pdf footer on each page of the pdf. The template of the footer can be changed by setting the pdf_footer option.

pdf_show_footer Example

pdf_show_footer=true
Not in view..

Change the default pdf footer that is shown on each page of the pdf when pdf_show_footer option is set.

You have the option to show the following variables in the footer (or header) of the pdf:

  • current date
  • title of the page
  • url of the page
  • current pageNumber
  • the totalPages in the pdf document

You can display these variables by creating empty divs or spans, with special css class names relating to the variable you want to show.

For example, if you want to show the date followed by the url, you could use the following pdf footer template:

<div class="date"></div><div class="url"></div>.

The pdf footer template you set are inserted as the innerHTML of a parent div which is a flex container, and has align-items set to flex-end.

There are also some helper classes for aligning the divs or spans. The following classes are available:

  • left - adds some left padding to the element and sets flex: none.
  • center - aligns the element and text to the center.
  • right - adds some right padding to the element and sets flex: none.
  • text - sets the text to 8pt.
  • grow - sets flex: auto on the element, allowing it to grow to fill the available space.

The default pdf footer is:

<div class='url text left grow'></div><div class='text right'><span class='pageNumber'></span>/<span class='totalPages'></span></div>.

You can see exactly how the pdf page is constructed by looking at the chromium pdf template in the chromium source repository.

pdf_footer Examples

Showing the date and url in the pdf footer.
Not in view..
Showing the current page and total pages in the pdf footer.
Not in view..

readable

Make the pdf into a readable document by removing unnecessary elements such as navigation bars, ads, etc.

readable Example

readable=true
Not in view..

Cache Options

Options to control how Urlbox caches your screenshots or PDF's. Please note that caching only applies to requests from render links. POST requests to the API are not cached.

force

default: false

Generate a fresh screenshot or PDF, instead of getting a cached version.

unique

Pass a unique string such as a UUID, hash or timestamp, to have more control over when to generate a fresh screenshot or PDF.

ttl

default: 2592000

The duration to keep a screenshot or PDF in the cache, in seconds. ttl stands for 'time to live'. The default value is also the maximum value: 2592000 seconds (30 days).

ttl Examples

no render link found
no render link found
no render link found

Request Options

Options to configure the browser, before navigating to the URL

proxy

Pass in a proxy server address to make screenshot requests via that server in the format [address]:[port].

If proxy authentication is required, you can use the following format: [user]:[password]@[address]:[port].

Set a header on the request when loading the URL

Example: To set the header with key X-My-Header to the value SomeValue, you would pass header=X-My-Header%3DSomeValue.

This can be set multiple times, to set more than one header - e.g. header=X-My-Header%3DSomeValue&header=X-My-Other-Header%3DSomeOtherValue.

As with all options passed via the query string, the header value must be URL encoded - so X-My-Header=SomeValue becomes X-My-Header%3DSomeValue in order to be interpreted correctly by Urlbox.

header Examples

header=X-My-Header=MyHeaderValue
Not in view..
Setting multiple headers
Not in view..

Sets a cookie on the request when loading the URL.

Example: To set the cookie with key Opt-In to the value yes, you would set the value of this option to Opt-In=yes.

Cookies can be passed as an array, to allow setting multiple cookies - e.g.["Opt-In=yes","Session-Id=DMTIzNDU"].

To achieve multiple cookies with render links, just set the cookie option multiple times, like cookie=Opt-In%3Dyes&cookie=Session-Id%3DDMTIzNDU.

To set a specific domain on a cookie, you can do the following: OptIn=yes;Domain=.mydomain.com.

You can set other attributes for the cookie such as Path, HttpOnly and SameSite

cookie Examples

cookie=OptIn=yes
Not in view..
Setting multiple cookies
Not in view..
Setting specific domain and other attributes for a cookie
Not in view..

user_agent

Sets the User-Agent string for the request

The presets are:

  • random - Uses a random user-agent to help avoid bot detection
  • mobile - Uses a 'mobile-like' user-agent string
  • desktop - Uses a 'desktop' user-agent string This can be used in some cases to emulate certain device types, like mobile phones or tablets.

user_agent Examples

user_agent=random
Not in view..
user_agent=mobile
Not in view..
user_agent=desktop
Not in view..
Google bot
Not in view..
Facebook crawler
Not in view..
Custom
Not in view..

platform

default: MacIntel

Sets the navigator.platform that the browser will report for the request. Useful for getting around certain scripts that detect the platform.

platform Examples

platform=MacIntel
Not in view..
platform=Linux x86_64
Not in view..
platform=Linux armv81
Not in view..
platform=Win32
Not in view..

accept_lang

default: en-US

Sets an Accept-Language header on requests to the target URL

accept_lang Examples

accept_lang=de-CH
Not in view..
accept_lang=ko-KR
Not in view..

authorization

Sets an Authorization header on requests to the target URL. Can be used to pass an auth token through to the site in order to 'login' before rendering.

authorization Examples

authorization=Basic my_base64_auth_token
Not in view..
authorization=Bearer my_bearer_token
Not in view..

tz

default: UTC

Emulate the timezone to use when rendering pages.

Example: tz=Europe/London. A list of timezone ID's can be found here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

tz Examples

tz=Asia/Kolkata
Not in view..
tz=Asia/Tokyo
Not in view..
tz=America/Sao_Paulo
Not in view..
tz=Europe/London
Not in view..

engine_version

default: stable

Sets the version of the urlbox rendering engine to use when rendering the page. This can be useful for testing how a page will render in the latest version of our rendering engine.

The available values are:

stable latest

Wait Options

Options to control how Urlbox waits for the page or elements to load before rendering.

delay

default: 0

The amount of time to wait before Urlbox captures a render in milliseconds.

timeout

default: 30000

The amount of time to wait for the requested URL to load, in milliseconds. The timeout value needs to be between 5,000 and 100,000 milliseconds. The default is 30000 or 30 seconds.

wait_until

default: loaded

Waits until the specified DOM event has fired before capturing a render.

The available options are:

  • domloaded (the DOMContentLoaded event is fired)
  • mostrequestsfinished (consider navigation to be finished when there are no more than 2 network connections for at least 500 ms)
  • requestsfinished (there are no more than 0 network connections for at least 500 ms)
  • loaded (the load event is fired)

wait_until Examples

wait_until=domloaded
Not in view..
wait_until=mostrequestsfinished
Not in view..
wait_until=requestsfinished
Not in view..
wait_until=loaded
Not in view..

wait_for

Waits for the element specified by this selector to be present in the DOM before taking a screenshot or PDF.

By default, Urlbox will take a screenshot or PDF if the wait_for element is not found after waiting for the time specified by the wait_timeout option.

If you prefer Urlbox to fail the request when the wait_for element is not found, pass fail_if_selector_missing=true

wait_for Examples

Without wait_for
Not in view..
wait_for=#loaded_element
Not in view..

wait_to_leave

Waits for the element specified by this selector to be absent from the DOM before taking a screenshot or PDF.

A typical use-case would be waiting for loading spinners to be absent before taking a screenshot.

By default, Urlbox will take a screenshot or PDF if the wait_to_leave element is still present after the time specified by the wait_timeout option.

If you prefer Urlbox to fail the request when the wait_to_leave element is still present, pass fail_if_selector_present=true

wait_to_leave Examples

Without wait_to_leave
Not in view..
wait_to_leave=#loading_element
Not in view..

wait_timeout

default: 30000

The amount of time to wait for the wait_for element to appear, or the wait_to_leave element to leave before continuing, in milliseconds.

Fail Options

Options to dictate how Urlbox handles certain scenarios.

fail_if_selector_missing

default: false

Fails the request if the elements specified by selector or wait_for options are not found on the page after waiting for wait_timeout.

fail_if_selector_present

default: false

Fails the request if the element specified by wait_to_leave option is found on the page after waiting for wait_timeout.

fail_on_4xx

default: false

If fail_on_4xx=true and the requested URL returns a status code between 400 and 499, Urlbox will fail the request with error code 400 and the message: Failed to render. Requested URL returned a 4xx error code and fail_on_4xx was true

fail_on_4xx Examples

fail_on_4xx=false
Not in view..
fail_on_4xx=true
Not in view..

fail_on_5xx

default: false

If fail_on_5xx=true and the requested URL returns a status code between 500 and 599, Urlbox will fail the request with error code 400 and message: Failed to render. Requested URL returned a 5xx error code and fail_on_5xx was true

fail_on_5xx Examples

fail_on_5xx=false
Not in view..
fail_on_5xx=true
Not in view..

Page Options

Options to modify the page state before taking a screenshot or PDF

scroll_to

Scroll, to either an element or to a pixel offset from the top, before taking a screenshot

scroll_to Examples

scroll_to=#playground
Not in view..
scroll_to=1024
Not in view..
scroll_to=5000
Not in view..

click

Specifies an element selector to click before generating a screenshot or PDF

Example: #clickme would click an element with id="clickme".

Can be used multiple times to simulate multiple sequential click events.

If the selector matches multiple elements, only the first element will be clicked.

click Examples

Minimizing the overlay
Not in view..
Without minimizing the overlay
Not in view..

click_all

Specifies an element selector to click before generating a screenshot or PDF

Example: .clickme would click all elements with class="clickme".

Can be used multiple times to simulate multiple sequential click events.

If the selector matches multiple elements, all elements will be clicked.

click_all Example

Navigate to a Sign-up page, and agree to policies.
Not in view..

hover

Specifies an element selector to hover over before generating a screenshot or PDF

Example: #hoverme would hover over the element with id="hoverme"

hover Examples

Hovering over the ruby-on-rails logo
Not in view..
Without hovering over the ruby-on-rails logo
Not in view..

bg_color

Specify a hex code or CSS color string to use as the background color

Some websites don't set a body background colour, and will show up as transparent backgrounds with PNG, or black when using JPG. Use this setting to set a background colour. If the website explicitly sets a transparent background on the html or body elements, this setting will be overridden.

disable_js

default: false

Turns off javascript on the target URL.

disable_js Examples

disable_js=true
Not in view..
disable_js=false
Not in view..

Full Page Options

Advanced options to control how Urlbox takes full page screenshots, when full_page=true

full_page_mode

default: stitch

Whether to use scroll and stitch algorithm (the default) to render a full page screenshot, or to use the native full page screenshot algorithm, which is faster, but can be less accurate on some sites.

The available values are:

stitch native

full_width

default: false

When full_page=true, specify whether to capture the full width of the website, for example if the site is horizontally scrolling.

allow_infinite

By default, when Urlbox detects an infinite scrolling page, it does not attempt to continue scrolling to the bottom, as this could result in infinite scrolling! If you want to override this behaviour, pass true for this option.

skip_scroll

default: false

Enabling skip_scroll will speed up renders by skipping an initial scroll through the page, which is used to trigger any lazy loading elements.

skip_scroll Examples

skip_scroll=true
Not in view..
skip_scroll=false
Not in view..

detect_full_height

Some pages have full-height backgrounds whose heights are set to 100% of the viewport. This can cause the backgrounds to get stretched when making a full page screenshot. If you are seeing this behaviour in your full page screenshots, pass true for this option.

max_section_height

default: 4096

When Urlbox takes a full_page screenshot, the maximum height of each image section is set to 4096 pixels. If a sites height is greater than this value, Urlbox will start splitting the screenshot into sections. Sometimes it is worthwhile experimenting with this number.

scroll_increment

Sets how many pixels to scroll when scrolling the page to trigger lazy loading elements. By default, the scroll increment is set to the browser viewport height. Some pages' lazy loading elements only trigger when the scroll increment is smaller than this, however, e.g. 400px.

scroll_delay

When Urlbox decides to split a screenshot into multiple sections, the scroll delay is the time to wait between taking the screenshots of each individual section, in milliseconds. While Urlbox does detect animations, and attempts to wait for them before taking a screenshot, this option could be used to force Urlbox to wait for a certain amount of time after scrolling to the next section, to wait for things like animations to finish.

Highlighting Options

Options for highlighting a given string on the page. These are useful for either highlighting or hiding (if you use the same foreground and background) words or a given set of characters.

highlight

Specify a string to highlight on the page before capturing a screenshot or PDF. To highlight multiple words, separate words with a pipe character e.g. Hello|World

highlight Example

highlight=urlbox|api
Not in view..

highlightfg

default: white

Specify the text color of the highlighted word.

highlightfg Examples

Using color name
Not in view..
Using rgb
Not in view..
Using rgba
Not in view..

highlightbg

default: red

Specify the background color of the highlighted word.

highlightbg Examples

Using color name
Not in view..
Using rgb
Not in view..
Using rgba
Not in view..

Geolocation Options

Options for the geolocation API.

latitude

Sets the latitude used to emulate the Geolocation API.

latitude Example

latitude=74.006
Not in view..

longitude

Sets the longitude used to emulate the Geolocation API.

longitude Example

longitude=40.7128
Not in view..

accuracy

Sets the accurate of the Geolocation API in metres.

accuracy Examples

accuracy=100
Not in view..
accuracy=5000
Not in view..

Storage Options

Options related to storing the screenshots in Amazon S3.

use_s3

default: false

Save the render directly to the S3 (or S3-Compatible) bucket configured on your account.

s3_path

Sets the S3 path, including subdirectories and the filename, to use when saving the render in your S3-compatible bucket.

s3_bucket

Overrides the configured bucket to use when saving the render.

s3_endpoint

You can change the endpoint URL to use an S3 compatible storage provider e.g. DigitalOcean Spaces, Minio, Wasabi, Cloudflare R2 and more.

s3_region

Override the configured S3 region when saving the render.

cdn_host

If your custom bucket is fronted by a CDN, you can set the host name here.

s3_storageclass

default: standard

Sets the s3 storage class.

The available values are:

standard standard_ia reduced_redundancy onezone_ia intelligent_tiering glacier deep_archive outposts