Skip to main content

​
Overview

Actions are the building blocks of webreel recordings. Each step in the steps array defines an action to perform. 
{
  "steps": [
    { "action": "pause", "ms": 500 },
    { "action": "click", "text": "Get Started" },
    { "action": "type", "text": "[email protected]", "selector": "#email" }
  ]
}

​
Common Fields

All actions (except pause) support these optional fields:
​
delay
number
Milliseconds to wait after completing the action. Overrides the video’s defaultDelay.
{ "action": "click", "text": "Submit", "delay": 1000 }
​
label
string
Custom text to display in the HUD overlay during this action. Overrides the default action label.
{ "action": "key", "key": "cmd+k", "label": "Open Command Palette" }
​
description
string
Internal description for documentation purposes. Not displayed during recording.

​
Element Targeting

Many actions accept element targeting fields:
​
text
string
Finds an element by its visible text content.
{ "action": "click", "text": "Sign In" }
​
selector
string
CSS selector to target a specific element.
{ "action": "click", "selector": "#submit-button" }
{ "action": "click", "selector": "button.primary" }
​
within
string
CSS selector to scope the search within a container element.
{
  "action": "click",
  "text": "Delete",
  "within": ".modal-dialog"
}
Specify either text or selector, not both. Use within to disambiguate when multiple matching elements exist.

​
Actions Reference

​
pause

Wait for a duration without performing any action.
​
action
'pause'
required
Action type.
​
ms
number
required
Milliseconds to pause.
{ "action": "pause", "ms": 1000 }
The pause action does not accept a delay field. Use ms to control the pause duration.

​
click

Move the cursor to an element and click it.
​
action
'click'
required
Action type.
​
text
string
Find element by visible text.
​
selector
string
CSS selector to target element.
​
within
string
Scope search to a container.
​
modifiers
string[]
Modifier keys to hold during the click. Valid values: "shift", "ctrl", "alt", "cmd", "meta".
{
  "action": "click",
  "text": "File.txt",
  "modifiers": ["cmd"]
}
​
delay
number
Milliseconds to wait after clicking.
​
label
string
Custom HUD label.
// Click by text
{ "action": "click", "text": "Get Started" }

// Click by selector
{ "action": "click", "selector": "#submit-btn" }

// Click with modifier
{
  "action": "click",
  "text": "Item 1",
  "modifiers": ["shift"],
  "delay": 500
}

// Click within container
{
  "action": "click",
  "text": "Delete",
  "within": ".modal"
}

​
type

Type text character by character into a focused element.
​
action
'type'
required
Action type.
​
text
string
required
Text to type.
​
selector
string
CSS selector of the input element. If omitted, types into the currently focused element.
​
within
string
Scope search to a container.
​
charDelay
number
default:"50"
Milliseconds to wait between each character.
​
delay
number
Milliseconds to wait after typing completes.
​
label
string
Custom HUD label.
// Type into focused element
{ "action": "type", "text": "[email protected]" }

// Type into specific selector
{
  "action": "type",
  "text": "password123",
  "selector": "#password",
  "delay": 500
}

// Type with custom char delay
{
  "action": "type",
  "text": "Slow typing...",
  "selector": "#message",
  "charDelay": 150
}

​
key

Press a key or key combination.
​
action
'key'
required
Action type.
​
key
string
required
Key or key combo to press. Examples: "Enter", "cmd+s", "shift+cmd+p".Common keys:
  • Letter keys: "a", "b", "z"
  • Special keys: "Enter", "Escape", "Tab", "Backspace", "Delete"
  • Arrow keys: "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"
  • Modifiers: "cmd", "ctrl", "shift", "alt", "meta"
​
target
string | ElementTarget
Element to focus before pressing the key. Can be a CSS selector string or an element target object.
{ "action": "key", "key": "Enter", "target": "#search-input" }
​
delay
number
Milliseconds to wait after pressing the key.
​
label
string
Custom HUD label.
// Press Enter
{ "action": "key", "key": "Enter" }

// Keyboard shortcut
{ "action": "key", "key": "cmd+s", "delay": 1000 }

// Multiple modifiers
{ "action": "key", "key": "shift+cmd+p", "label": "Command Palette" }

// Press key on specific element
{
  "action": "key",
  "key": "ArrowDown",
  "target": "#dropdown"
}

​
scroll

Scroll the page or a specific element.
​
action
'scroll'
required
Action type.
​
x
number
Horizontal scroll position in pixels.
​
y
number
Vertical scroll position in pixels.
​
selector
string
CSS selector of the element to scroll. If omitted, scrolls the page.
​
text
string
Find element to scroll by visible text.
​
within
string
Scope search to a container.
​
delay
number
Milliseconds to wait after scrolling.
​
label
string
Custom HUD label.
// Scroll page vertically
{ "action": "scroll", "y": 500 }

// Scroll horizontally
{ "action": "scroll", "x": 200, "y": 0 }

// Scroll specific element
{
  "action": "scroll",
  "y": 300,
  "selector": ".scrollable-container",
  "delay": 800
}

​
wait

Wait for an element to appear in the DOM.
​
action
'wait'
required
Action type.
​
selector
string
CSS selector of the element to wait for.
​
text
string
Wait for element with visible text.
​
within
string
Scope search to a container.
​
timeout
number
default:"30000"
Maximum milliseconds to wait before failing.
​
delay
number
Milliseconds to wait after element appears.
​
label
string
Custom HUD label.
// Wait for element by selector
{ "action": "wait", "selector": ".loading-complete" }

// Wait for text content
{ "action": "wait", "text": "Dashboard loaded" }

// Wait with custom timeout
{
  "action": "wait",
  "selector": ".slow-component",
  "timeout": 60000,
  "delay": 500
}

​
drag

Drag an element from one position to another.
​
action
'drag'
required
Action type.
​
from
ElementTarget
required
Source element to drag. Object with text, selector, and/or within fields.
​
to
ElementTarget
required
Destination element or position. Object with text, selector, and/or within fields.
​
delay
number
Milliseconds to wait after dragging.
​
label
string
Custom HUD label.
// Drag by text
{
  "action": "drag",
  "from": { "text": "Task 1" },
  "to": { "text": "Done" }
}

// Drag with containers
{
  "action": "drag",
  "from": {
    "text": "Write tests",
    "within": ".todo-column"
  },
  "to": {
    "selector": ".card-list",
    "within": ".in-progress-column"
  },
  "delay": 600
}

​
moveTo

Move the cursor to an element without clicking.
​
action
'moveTo'
required
Action type.
​
text
string
Find element by visible text.
​
selector
string
CSS selector to target element.
​
within
string
Scope search to a container.
​
delay
number
Milliseconds to wait after moving.
​
label
string
Custom HUD label.
// Move to element by text
{ "action": "moveTo", "text": "Settings" }

// Move to element by selector
{
  "action": "moveTo",
  "selector": ".nav-item",
  "delay": 400
}

​
hover

Hover over an element, triggering CSS :hover effects.
​
action
'hover'
required
Action type.
​
text
string
Find element by visible text.
​
selector
string
CSS selector to target element.
​
within
string
Scope search to a container.
​
delay
number
Milliseconds to wait after hovering.
​
label
string
Custom HUD label.
// Hover by text
{ "action": "hover", "text": "Products" }

// Hover by selector with delay
{
  "action": "hover",
  "selector": ".dropdown-trigger",
  "delay": 800
}
Navigate to a new URL mid-recording.
​
action
'navigate'
required
Action type.
​
url
string
required
URL to navigate to. Can be absolute or relative to the video’s baseUrl.
​
delay
number
Milliseconds to wait after navigation completes.
​
label
string
Custom HUD label.
// Navigate to new page
{ "action": "navigate", "url": "/dashboard" }

// Navigate with delay
{
  "action": "navigate",
  "url": "https://example.com/products",
  "delay": 1000
}

​
screenshot

Capture a PNG screenshot at the current point in the recording.
​
action
'screenshot'
required
Action type.
​
output
string
required
File path for the screenshot. Relative to the video’s outDir.
​
delay
number
Milliseconds to wait after capturing the screenshot.
​
label
string
Custom HUD label.
// Capture screenshot
{ "action": "screenshot", "output": "dashboard.png" }

// Multiple screenshots
{
  "steps": [
    { "action": "click", "text": "Features" },
    { "action": "screenshot", "output": "features-page.png" },
    { "action": "click", "text": "Pricing" },
    { "action": "screenshot", "output": "pricing-page.png" }
  ]
}

​
select

Select a value in a dropdown (<select>) element.
​
action
'select'
required
Action type.
​
value
string
required
Value to select (matches the <option> element’s value attribute).
​
selector
string
CSS selector of the <select> element.
​
text
string
Find <select> element by nearby text.
​
within
string
Scope search to a container.
​
delay
number
Milliseconds to wait after selecting.
​
label
string
Custom HUD label.
// Select by value
{
  "action": "select",
  "selector": "#country",
  "value": "us"
}

// Select with delay
{
  "action": "select",
  "selector": "#theme",
  "value": "dark",
  "delay": 500
}

​
Complete Example

{
  "$schema": "https://webreel.dev/schema/v1.json",
  "videos": {
    "onboarding-flow": {
      "url": "https://myapp.com/signup",
      "viewport": { "width": 1920, "height": 1080 },
      "defaultDelay": 600,
      "steps": [
        { "action": "pause", "ms": 500 },
        { "action": "type", "text": "Alice Smith", "selector": "#name" },
        { "action": "type", "text": "[email protected]", "selector": "#email" },
        { "action": "select", "selector": "#country", "value": "us" },
        { "action": "click", "text": "Continue", "delay": 1000 },
        { "action": "wait", "selector": ".welcome-screen" },
        { "action": "screenshot", "output": "welcome-screen.png" },
        { "action": "key", "key": "cmd+k", "label": "Command Palette" },
        { "action": "type", "text": "create project" },
        { "action": "key", "key": "Enter", "delay": 800 },
        { "action": "scroll", "y": 300 },
        {
          "action": "drag",
          "from": { "text": "Module A" },
          "to": { "text": "Active Projects" },
          "delay": 1000
        },
        { "action": "moveTo", "text": "Settings" },
        { "action": "hover", "selector": ".profile-menu", "delay": 500 },
        { "action": "pause", "ms": 1000 }
      ]
    }
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us