Skip to main content
Some workflows need a keyboard modifier to be held down while another action runs — for example, holding shift while clicking to extend a selection, holding ctrl while clicking multiple files, or holding alt while scrolling to trigger an alternate gesture. The key action supports an optional down parameter that controls whether the key is pressed, held, or released. Pair a down=true call with a later down=false call on the same key so the key never ends up stuck in the pressed state.

​
The down parameter

down is tri-state:
down valueBehavior
omitted (default)Full press: press the key down and release it immediately. Backwards-compatible with the normal key action.
truePress the key down and hold it without releasing.
falseRelease a key that was previously held with down=true.
down only applies to the key action. It is ignored for type and every other action.

​
Basic usage pattern

To hold a key while performing another action:
1

Press the key down and hold

Call key with the key chord and down=true. The key stays pressed until you release it.
2

Perform the action

Call left_click, mouse_move, scroll, or any other action while the key is held.
3

Release the key

Call key again with the same key and down=false to release it.

​
Example: shift-click to extend a selection

1. Use `left_click` at the first item's coordinates to select it.
2. Use `key` with text="shift" and down=true to press and hold Shift.
3. Use `left_click` at the last item's coordinates to extend the selection.
4. Use `key` with text="shift" and down=false to release Shift.

​
Example: ctrl-click to toggle multi-select

1. Use `left_click` to select the first item.
2. Use `key` with text="ctrl" and down=true to press and hold Ctrl.
3. Use `left_click` to toggle each additional item.
4. Use `key` with text="ctrl" and down=false to release Ctrl.

​
Example: ctrl-scroll to zoom

1. Use `key` with text="ctrl" and down=true to press and hold Ctrl.
2. Use `scroll` with scroll_direction="up" and scroll_amount=3 to zoom in.
3. Use `key` with text="ctrl" and down=false to release Ctrl.

​
Guidelines

  • Always pair down=true with a matching down=false. If you hold a modifier and forget to release it, every subsequent action in the workflow will be affected, and downstream typing or shortcuts will behave unexpectedly.
  • Release the same key you pressed. If you pressed shift down, release shift, not lshift or shiftleft.
  • Avoid key chords with down=true. down is designed for simple modifier keys like shift, ctrl, alt, and win. Do not use it with chords such as ctrl+shift.
  • Prefer the default full-press form when you don’t need to hold. If you just need ctrl+a as a one-shot, use action="key" with text="ctrl+a" and no down parameter. That’s the normal behavior.
  • Take a screenshot after releasing if you need to verify the result. The screenshot after a down=true call shows the screen while the key is held, which is usually not what you want to verify against.

​
Comparison with modifier-click shortcuts

For simple modifier combinations like ctrl+a (select all), ctrl+c (copy), or alt+tab (switch window), keep using the default key action with the chord directly: 
action="key", text="ctrl+a"
This presses and releases the chord in one atomic step. You only need the down parameter when the held key has to span another action, such as a click, a mouse move, or a scroll.