Skip to content
HTML/CSS to ImageDocs

Script scrolling, clicks, waits, and JavaScript during a recording

actions is an ordered array that runs during a recording, starting when the trigger fires. Each action finishes before the next one starts.

Pass actions as a JSON array, not a JSON string. The recording deadline set by duration_ms and duration_mode can cut any action short.

When any action scrolls, the page is scrolled down and back up before recording starts, so lazy-loaded images are already showing. See skip_scroll_preload.

When actions is left out, nothing happens on the page. The recording captures the page as it is for the full duration_ms, including any animations, videos, or timers that are already playing.

actions is an array of objects. Each object’s type field selects one of the action types below:

Type What it does
simple_scroll Scroll down the page step by step until the bottom or the deadline
scroll Scroll to exact positions, elements, or coordinates, in the page or a scrollable container
stall Wait while the page keeps playing
click Click an element, scrolling it into view first if needed
locate_selector Check for an element and run different actions depending on whether it’s there
execute_javascript Run JavaScript in the page
error Fail the recording on purpose

Scrolls down in repeated steps until it reaches the bottom of the page or runs out of time. It’s the easiest way to record a website walkthrough.

{ "type": "simple_scroll" }
Field Type Default Description
type String Required. simple_scroll
scroll_duration_ms Integer 800 Length of each scroll movement, 1–90000 ms. Higher values scroll more slowly.
ms_between_scrolls Integer 400 Pause after each movement, 0–90000 ms. Higher values give viewers more reading time.
scroll_distance Number or String "90vh" Distance of each step. A number of CSS pixels (900), a px string ("900px"), or a viewport-height string ("90vh").
easing String ease_in_out_expo Easing for each movement.
stall_at_end_ms Integer 0 Time to hold at the bottom, 0–90000 ms, if time remains.

A short recording of a long page may not reach the bottom. Increase duration_ms, make scroll_distance larger, or make ms_between_scrolls shorter.

Scrolls through a list of exact, timed steps. Use it to scroll to a specific section, scroll back up, or scroll inside a container like a chat window or code panel.

{
"type": "scroll",
"steps": [
{ "to": { "type": "selector", "selector": "#features", "offset_y": -80 }, "duration_ms": 1500, "easing": "ease_in_out_cubic" },
{ "to": { "type": "position", "position": "bottom" }, "duration_ms": 3000 },
{ "to": { "type": "position", "position": "top" }, "duration_ms": 1000, "easing": "ease_out_expo" }
]
}
Field Type Default Description
type String Required. scroll
steps Array Required. One or more movements, run in order.
container_selector String CSS selector for a scrollable element. Leave it out to scroll the page.
if_not_found Array Actions to run if container_selector doesn’t match anything. If left out or empty, the scroll is skipped. It never falls back to the page.

Each step in steps:

Field Type Default Description
to Object Required. The destination. See the target types below.
duration_ms Integer Required. How long the movement takes, at least 1 ms.
easing String linear Easing curve.

to with "type": "position" scrolls to an edge of the page or container:

Field Type Default Description
position String top top, bottom, left, or right.

to with "type": "coordinates" scrolls to an exact position:

Field Type Default Description
x Number 0 Horizontal scroll position in CSS pixels.
y Number 0 Vertical scroll position in CSS pixels.

to with "type": "selector" scrolls to an element:

Field Type Default Description
selector String Required. CSS selector for the destination element.
offset_x Number 0 Horizontal offset in CSS pixels added to the element’s position.
offset_y Number 0 Vertical offset in CSS pixels added to the element’s position.
if_not_found Array Actions to run if the element is missing. If left out or empty, the step is skipped.

Waits while recording continues. Animations, videos, and timers on the page keep playing.

{ "type": "stall", "duration_ms": 2000 }
Field Type Default Description
type String Required. stall
duration_ms Integer Required. How long to wait, in milliseconds. Must be 0 or more.

To wait before capture instead, use a trigger.

Finds an element, scrolls it into view if needed, and clicks it.

{ "type": "click", "selector": "button.accept", "timeout_ms": 2000, "if_not_found": [] }
Field Type Default Description
type String Required. click
selector String Required. CSS selector to click.
timeout_ms Integer 0 How long to wait for the element. 0 checks once.
if_not_found Array Actions to run if the element isn’t found. If left out or empty, the recording continues.
button String left left, right, middle, back, or forward.
count Integer 1 The click count reported to the page, 1–3. Use 2 for a double-click event. It doesn’t repeat the click.
delay_ms Integer 0 Time between mouse down and mouse up, 0–5000 ms.
offset_x Number Horizontal click position in CSS pixels from the element’s top-left corner.
offset_y Number Vertical click position in CSS pixels from the element’s top-left corner.

If you set one offset, the other defaults to 0. With neither, the element’s normal click point is used.

Checks whether an element exists and runs one of two branches. Use it for things that may or may not appear, like cookie prompts, promo modals, or A/B-tested sections.

{
"type": "locate_selector",
"selector": "#newsletter-modal",
"timeout_ms": 1500,
"if_found": [
{ "type": "click", "selector": "#newsletter-modal .close" },
{ "type": "stall", "duration_ms": 300 }
],
"if_not_found": []
}
Field Type Default Description
type String Required. locate_selector
selector String Required. CSS selector to look for.
timeout_ms Integer 0 How long to wait for it. 0 checks once.
if_found Array Actions to run when it’s found. If left out or empty, the recording continues.
if_not_found Array Actions to run when it isn’t found in time. If left out or empty, the recording continues.

Branch actions don’t inherit the selector. Each action inside a branch needs its own selector. At least one branch must be able to continue without an error action.

Runs JavaScript in the page while recording continues. script is the body of an async function, so you can use await. The return value is ignored.

{
"type": "execute_javascript",
"script": "document.querySelector('#theme').click(); await new Promise(r => setTimeout(r, 500));",
"timeout_ms": 3000,
"if_error": []
}
Field Type Default Description
type String Required. execute_javascript
script String Required. An async function body.
timeout_ms Integer 0 Maximum run time, up to 90000 ms. 0 uses the page timeout.
if_error Array Leave it out or set it to null to fail the recording on an error or timeout. Use [] to ignore errors, or an array of recovery actions to run instead.

Frames keep being captured while the script runs, including during await. A timeout doesn’t undo the script’s side effects or cancel timers and promises it already started.

To wait inside a script, await a timer. Don’t use a busy loop.

Fails the recording right away with the action_error code. It must be the last action in its array.

Field Type Default Description
type String Required. error
{
"type": "locate_selector",
"selector": "#pricing",
"timeout_ms": 3000,
"if_not_found": [{ "type": "error" }]
}

Use it when a missing element means the video would be wrong, so a recording that’s ready always shows what you expect. The failed recording’s action_path (for example actions[0].if_not_found[0]) shows which branch failed.

  • if_found, if_not_found, and if_error hold ordinary action arrays. When a branch finishes, the recording continues with the next action after the parent.
  • A branch that’s left out, null, or empty just continues. Add an error action to fail instead. (execute_javascript.if_error is the exception: leaving it out fails the recording.)
  • Branches can nest up to 16 levels deep.
  • An error action must be last in its array.

easing on simple_scroll and scroll steps sets the shape of each movement. Every family has ease_in_* (start slow), ease_out_* (end slow), and ease_in_out_* (both) versions. To see how each curve moves, visit easings.net. The names match, for example easeInOutCubic is ease_in_out_cubic.

Value Feel
linear Constant speed
ease_in_quad, ease_out_quad, ease_in_out_quad Gentle
ease_in_cubic, ease_out_cubic, ease_in_out_cubic Natural, a good general choice
ease_in_quart, ease_out_quart, ease_in_out_quart Stronger than cubic
ease_in_quint, ease_out_quint, ease_in_out_quint Stronger than quartic
ease_in_sine, ease_out_sine, ease_in_out_sine Very soft
ease_in_expo, ease_out_expo, ease_in_out_expo Fast in the middle with long, slow ends. Default for simple_scroll.
ease_in_circ, ease_out_circ, ease_in_out_circ Sharp change in speed
ease_in_back, ease_out_back, ease_in_out_back Pulls back or overshoots slightly
ease_in_elastic, ease_out_elastic, ease_in_out_elastic Springy oscillation
ease_in_bounce, ease_out_bounce, ease_in_out_bounce Bounces at the end or start

Overshoot from back and elastic curves is limited by the edges of the page.

{
"url": "https://example.com/",
"duration_ms": 15000,
"actions": [
{ "type": "stall", "duration_ms": 1500 },
{ "type": "simple_scroll", "stall_at_end_ms": 1000 }
]
}
{
"html": "<h1>Version 2.0 is out.</h1>",
"css": "h1 { opacity: 0; } .recording h1 { animation: reveal 1s both; } @keyframes reveal { to { opacity: 1; } }",
"duration_ms": 4000,
"duration_mode": "fixed",
"actions": [{ "type": "execute_javascript", "script": "document.body.classList.add('recording');" }]
}
{
"url": "https://example.com/pricing",
"duration_ms": 10000,
"duration_mode": "fixed",
"actions": [
{ "type": "click", "selector": ".newsletter-modal .close", "timeout_ms": 2000, "if_not_found": [] },
{ "type": "click", "selector": "[data-tab='annual']" },
{ "type": "stall", "duration_ms": 2000 },
{ "type": "click", "selector": "[data-tab='enterprise']" }
]
}
Use case Actions
Scroll through a landing page simple_scroll
Highlight specific sections scroll with selector targets
Record an animation execute_javascript to start it, then stall or fixed mode
Product demo click, stall, and locate_selector for optional popups
Scroll a chat window or code panel scroll with container_selector

See the recording guides for complete walkthroughs.

Need help?

Talk to a human. Email support@htmlcsstoimage.com and we’ll help you get started.