Actions

Actions are the individual steps that make up a video. Each step in the steps array has an action field and action-specific parameters.

Every step also accepts an optional description field (string) for documentation purposes. Descriptions are shown in --verbose and --dry-run output but otherwise ignored at runtime.

Steps that target elements accept text, selector, and within fields to identify the element.

Every step (except pause) also accepts an optional label field (shown on-screen during recording) and an optional delay field (milliseconds to wait after the step executes). See delay and defaultDelay and Step label and description for details.

pause

Wait for a duration before continuing to the next step.

{ "action": "pause", "ms": 500 }

Field	Type	Description
`ms`	number	Duration in milliseconds

click

Move the cursor to an element and click it.

{ "action": "click", "text": "Get Started" }
{ "action": "click", "selector": "#submit-btn" }
{ "action": "click", "text": "Save", "within": ".modal" }

Field	Type	Description
`text`	string	Text content to find the element by
`selector`	string	CSS selector to find the element
`within`	string	Narrow the search to elements within this selector
`modifiers`	string[]	Modifier keys to hold during click

Provide either text or selector, not both.

key

Press a key or key combination.

{ "action": "key", "key": "mod+a" }
{ "action": "key", "key": "Enter", "label": "Submit" }
{ "action": "key", "key": "Escape", "target": "#modal" }

Use mod+ as a platform-agnostic modifier. It maps to Cmd on macOS and Ctrl on other platforms. You can also use cmd+ or ctrl+ explicitly.

Field	Type	Description
`key`	string	Key or combo (e.g. `"mod+z"`, `"Enter"`, `"shift+tab"`)
`target`	string or object	CSS selector string, or element target object, to focus before pressing the key
`label`	string	Optional label shown in the keystroke overlay

type

Type a string of text character by character. Useful for filling form fields with a realistic typing animation.

{ "action": "type", "text": "hello@example.com" }
{ "action": "type", "text": "search query", "selector": "#search" }

Field	Type	Description
`text`	string	The text to type
`selector`	string	CSS selector of the element to click before typing
`within`	string	Narrow the search to elements within this selector
`charDelay`	number	Milliseconds between each keystroke (default: 80)

scroll

Scroll the page or a specific element.

{ "action": "scroll", "y": 300 }
{ "action": "scroll", "y": -200, "selector": ".sidebar" }

Field	Type	Description
`x`	number	Horizontal scroll offset in pixels
`y`	number	Vertical scroll offset in pixels
`text`	string	Text content to find the element to scroll
`selector`	string	CSS selector of the element to scroll (defaults to the window)
`within`	string	Narrow the search to elements within this selector

wait

Wait for an element to appear before continuing.

{ "action": "wait", "selector": ".loaded" }
{ "action": "wait", "text": "Welcome back", "timeout": 5000 }

Field	Type	Description
`selector`	string	CSS selector to wait for
`text`	string	Text content to wait for
`within`	string	Narrow the search to elements within this selector
`timeout`	number	Maximum wait time in milliseconds (default: 30000)

Provide either selector or text, not both.

screenshot

Capture a PNG screenshot at a specific point during the recording.

{ "action": "screenshot", "output": "hero.png" }

Field	Type	Description
`output`	string	File path to save the screenshot

drag

Drag from one element to another.

{
  "action": "drag",
  "from": { "text": "Item 1" },
  "to": { "text": "Drop Zone" }
}

Field	Type	Description
`from`	object	Source element (`text`, `selector`, or `within`)
`to`	object	Target element (`text`, `selector`, or `within`)

moveTo

Move the cursor to an element without clicking.

{ "action": "moveTo", "text": "Settings" }
{ "action": "moveTo", "selector": ".nav-item" }

Field	Type	Description
`text`	string	Text content to find the element by
`selector`	string	CSS selector to find the element
`within`	string	Narrow the search to elements within this selector

navigate

Navigate to a new URL during a recording. Useful for multi-page flows where you need to visit a different route mid-video.

{ "action": "navigate", "url": "/dashboard" }
{ "action": "navigate", "url": "https://example.com/settings" }

Field	Type	Description
`url`	string	URL to navigate to (resolved against `baseUrl` if relative)

hover

Hover over an element, triggering any CSS hover states or JavaScript hover handlers.

{ "action": "hover", "text": "Settings" }
{ "action": "hover", "selector": ".dropdown-trigger" }
{ "action": "hover", "text": "Menu", "within": ".nav" }

Field	Type	Description
`text`	string	Text content to find the element by
`selector`	string	CSS selector to find the element
`within`	string	Narrow the search to elements within this selector

Provide either text or selector, not both.

select

Select a value from a <select> dropdown element.

{ "action": "select", "value": "us", "selector": "#country" }
{ "action": "select", "value": "dark", "text": "Theme" }

Field	Type	Description
`value`	string	The option value to select
`text`	string	Text content to find the select element by
`selector`	string	CSS selector to find the select element
`within`	string	Narrow the search to elements within this selector

Provide either text or selector, not both.